# Overview

> The miso command line tool: build, run and serve miso apps with MicroHs, without GHC.

Source: https://haskell-miso.org/docs/cli/

`miso` is one binary that creates, builds, runs and serves miso applications. It has [MicroHs](https://github.com/augustss/MicroHs) (`mhs`) and [MicroCabal](https://github.com/augustss/MicroCabal) (`mcabal`) built in, so there is no GHC to install: a project is a `miso.yml`, and its packages come from Hackage.

## Install

On Linux and macOS (Intel and Apple Silicon), and on Windows in an [MSYS2](https://www.msys2.org) shell:

```shell
$ curl -fsSL https://haskell-miso.org/download | sh
```

The installer downloads the release for your OS and architecture from [haskell-miso/cli](https://github.com/haskell-miso/cli/releases), checks its sha256, unpacks it in `~/.miso` (or `$MISO_HOME`), and offers to add `~/.miso/bin` to your `PATH`. It shows what it will do and asks first; `sh -s -- --yes` takes the defaults, and `--no-modify-path` leaves your shell's startup files alone. `MISO_VERSION=v0.1.0` installs a given release.

With nix, the release is a flake package: `nix profile install github:haskell-miso/cli#release`.

## Your first app

```shell
$ miso doctor
$ miso new counter
$ cd counter
$ miso dev
```

`miso doctor` checks the installation and the tools miso needs, and says how to fix what is missing. `miso new` makes a project from a template; `miso dev` builds it, serves `public/` on `http://localhost:8000`, and rebuilds and reloads the page on every save.

> **Note:** A new project builds for the browser (`target: browser`, WebAssembly), which needs [emscripten](https://emscripten.org) (`emcc`). Without it, set `target: native` in `miso.yml` and use `miso run`.

## Requirements

- A C compiler (`cc`): mhs compiles programs to C.
- For the browser targets (`browser`, `browser_js`), [emscripten](https://emscripten.org) (`emcc`).
- `curl`, `tar`, `sha256sum` or `shasum`, and `git` for git dependencies.
- [hlint](https://github.com/ndmitchell/hlint), for `miso lint` only.

On Windows, install the tools in MSYS2 first: `pacman -S gcc make tar curl git`.

## Every command

| Command | What it does |
| --- | --- |
| [`miso new NAME`](https://haskell-miso.org/docs/cli-projects/) | a new project from a template |
| [`miso templates`](https://haskell-miso.org/docs/cli-projects/) | list the templates |
| [`miso init`](https://haskell-miso.org/docs/cli-projects/) | make the current directory a project |
| [`miso build [NAME...]`](https://haskell-miso.org/docs/cli-projects/) | build the project, or the programs named |
| [`miso run [NAME] [ARGS]`](https://haskell-miso.org/docs/cli-projects/) | build a native program and run it |
| [`miso test [NAME...]`](https://haskell-miso.org/docs/cli-projects/) | build the tests and run them |
| [`miso dev [NAME]`](https://haskell-miso.org/docs/cli-projects/) | build, serve, and rebuild and reload on every change |
| [`miso serve`](https://haskell-miso.org/docs/cli-projects/) | serve `public/` as it is |
| [`miso watch [NAME]`](https://haskell-miso.org/docs/cli-projects/) | type check on every change, and show the first error |
| [`miso lint [ARGS]`](https://haskell-miso.org/docs/cli-projects/) | run hlint on the sources |
| [`miso repl`](https://haskell-miso.org/docs/cli-projects/) | MicroHs, interactively, with the project's modules |
| [`miso clean`](https://haskell-miso.org/docs/cli-projects/) | remove what builds make |
| [`miso install`](https://haskell-miso.org/docs/cli-dependencies/) | install the dependencies of `miso.yml` |
| [`miso add PKG...`](https://haskell-miso.org/docs/cli-dependencies/) | add Hackage packages, and install them |
| [`miso remove PKG...`](https://haskell-miso.org/docs/cli-dependencies/) | remove dependencies |
| [`miso list`](https://haskell-miso.org/docs/cli-dependencies/) | the installed packages |
| [`miso lock`](https://haskell-miso.org/docs/cli-dependencies/) | write `miso.lock` |
| [`miso update`](https://haskell-miso.org/docs/cli-dependencies/) | lock again at the newest versions, and install |
| [`miso vendor`](https://haskell-miso.org/docs/cli-dependencies/) | copy the locked sources to `vendor/` |
| [`miso cabal`](https://haskell-miso.org/docs/cli-dependencies/) | print the `.cabal` file of the library |
| [`miso doctor`](https://haskell-miso.org/docs/cli-tool/) | check the installation and the tools |
| [`miso upgrade [VERSION]`](https://haskell-miso.org/docs/cli-tool/) | install the latest release, or VERSION |
| [`miso uninstall`](https://haskell-miso.org/docs/cli-tool/) | remove miso |
| [`miso version`](https://haskell-miso.org/docs/cli-tool/) | the versions of miso and MicroHs |
| [`miso help`](https://haskell-miso.org/docs/cli-tool/) | the commands |
| [`miso mhs ARGS`](https://haskell-miso.org/docs/cli-tool/) | the MicroHs compiler built into the tool |
| [`miso mcabal ARGS`](https://haskell-miso.org/docs/cli-tool/) | MicroCabal, compiling with `miso mhs` |

## Conventions

- Commands that work on a project read `miso.yml` in the current directory (not a parent), and fail without one. The others are `new`, `templates`, `init`, `serve`, `repl`, `list` and the commands of the tool itself.
- `==>` lines say what miso is doing or has done, `->` lines are steps of it; `warning:` and `error:` go to standard error. `NO_COLOR=1` turns colors off.
- The exit status is 0 when the command worked and 1 when it failed. `miso run` and `miso lint` exit with the status of the program or of hlint; Ctrl-C exits with 130.
- Commands that build install the dependencies first, when they are not installed yet.

## Environment variables

| Variable |  |
| --- | --- |
| `MISO_HOME` | where miso keeps downloads, git checkouts, the package list, the store and dev runtimes (default `~/.miso`); the installer installs there too |
| `NO_COLOR` | set (non-empty) to turn off colors |
| `MISO_INSTALL_URL` | where `miso upgrade` downloads the installer from |
| `MISO_VERSION` | for the installer: the release to install (default the latest) |
| `MISO_RELEASE_URL` | for the installer: a mirror of the release files (or `file://`) |
| `MISO_REPO` | for the installer: the GitHub repository of the releases (default `haskell-miso/cli`) |
| `MHSCPPHS` | the `cpphs` mhs runs for modules with CPP (default the one next to `miso`) |

## Files and directories

In a project:

| Path |  |
| --- | --- |
| `miso.yml` | the project: see [miso.yml](https://haskell-miso.org/docs/cli-miso-yml/) |
| `miso.lock` | the locked dependencies; commit it |
| `vendor/` | vendored sources (`miso vendor`); commit it |
| `.miso/` | installed packages |
| `dist/` | native programs and tests |
| `public/` | browser programs, and their static files |
| `.miso-build.log` | the log of the last build |

In `$MISO_HOME` (default `~/.miso`):

| Path |  |
| --- | --- |
| `bin/miso`, `bin/cpphs`, `mhs-VERSION/` | the tool and its package database (when the installer installed it) |
| `src/` | downloads and git checkouts |
| `mcabal/` | MicroCabal's package list |
| `store/` | built packages, shared by projects |
| `rts/` | the browser runtimes of `miso dev` |

## In CI

The [setup-miso](https://github.com/haskell-miso/setup-miso) GitHub Action installs a release and builds and tests a project with it:

```
- uses: haskell-miso/setup-miso@main
  with:
    version: latest
```