# Project commands

> miso new, init, build, run, test, dev, serve, watch, lint, repl and clean.

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

Making a project, building it, running it, and the loop of editing and reloading.

### miso new

```
miso new NAME [--template T]
```

Makes a directory `NAME` with a new project from a template (default `counter`):

| File |  |
| --- | --- |
| `miso.yml` | `name: NAME`, `version: 0.1.0`, `main: Main`, `source-dirs: [app]`, `target: browser`, `dependencies: [miso]` |
| `app/Main.hs` | the template's program |
| `static/index.html` | the page that loads the program (copied to `public/` by builds) |
| `.gitignore` | `public/`, `dist/`, `.miso/`, `.mhscache`, `.miso-build.log` |
| `README.md` | how to build it |

Fails when `NAME` exists already, or the template does not (it then lists the templates).

### miso templates

```
miso templates
```

Lists the templates: `counter` (the smallest miso app, the default), `router` (pages with URLs, and links between them) and `canvas` (drawing on a canvas, driven by the model).

### miso init

```
miso init [--name NAME] [--version V] [--synopsis S] [--author A]
          [--license L] [--template T] [--yes]
```

Makes the current directory a project, keeping the files that are there. On a terminal it asks for each value the flags do not give, showing the default:

| Question | Default | Accepted |
| --- | --- | --- |
| name | the directory's name | a letter, then letters, digits and `-` |
| version | `0.1.0` | numbers separated by dots |
| synopsis | none | anything |
| author | `git config user.name` `<user.email>` | anything |
| license | `BSD-3-Clause` | an SPDX id, or `none` |
| template | `counter` | `counter`, `router`, `canvas` |

With `--yes`, or when the input is not a terminal, it takes the defaults without asking. It writes the template's files that are not there yet; one that is there is kept, except `.gitignore`, which gets the lines it lacks. A `LICENSE` file is written for `MIT`, `BSD-2-Clause` and `BSD-3-Clause`. Fails in a directory that has `miso.yml` already.

### miso build

```
miso build [NAME...]
```

Builds the project: type checks the library, if there is one (`mhs -fno-code`), and builds every program; or, with names, only those programs.

- A `native` program (a program without `target:` is one) is built to `dist/NAME`.
- A browser program (`browser`: WebAssembly, `browser_js`: JavaScript) is built to `public/index.js`, next to a copy of its `static-dir` (default `static/`); with several browser programs, each to `public/NAME/`.
- Tests are not built (`miso test` builds them).

Before installing anything it checks that `emcc` is there when a program needs it, and says where to get it. On a terminal it shows the build as it runs, then what mhs said; the whole log is `.miso-build.log`. `miso build --dev NAME` is the build `miso dev` runs: for a `browser` program it writes the program as combinators (`app.comb`) and a runtime built once with emcc (kept in `$MISO_HOME/rts`; no emcc is needed when it is there already).

### miso run

```
miso run [NAME] [ARGS...]
miso run [NAME] -- ARGS...
```

Builds a native program and runs it with `ARGS`: the program named, when the first argument is the name of one, otherwise the first native program of `miso.yml`. It exits with the program's exit status, and fails for a browser program (use `miso dev` or `miso serve`).

### miso test

```
miso test [NAME...] [-- ARGS...]
```

Builds the tests of `miso.yml` (the `tests:` section, or those named) to `dist/NAME`, and runs each with `ARGS`. A test passes when it exits with 0. All of them run; then it says how many passed, and fails when one did not (`1 of 2 tests failed: fail`).

### miso dev

```
miso dev [NAME] [--port N]
```

For a browser program (the one named, or the first): serves `public/` on `http://localhost:PORT/`, builds the program, and builds it again whenever one of these changes, reloading the page when the build works:

- the source dirs of the program and of the library,
- its `static-dir`,
- `cbits/`, `jsbits/`, `include/`, and the dirs of its C and JavaScript files,
- `miso.yml`, and the directories of `path:` dependencies.

PORT is N, or the first free port from 8000 to 8099. A build that fails shows its log and keeps the last build in the page. With the browser runtime built once, a save does not run emcc: it only compiles the program to combinators. It runs until Ctrl-C.

### miso serve

```
miso serve [--port N]
```

Serves `public/` as it is (no build, no reload) on N, or the first free port from 8000. Fails when there is no `public/`.

### miso watch

```
miso watch [NAME]
```

Type checks the library, the programs and the tests (or the one named) with `mhs -fno-code`, then again on every change, as [ghcid](https://github.com/ndmitchell/ghcid) does. It shows `All good` or the first error, as `file:line:col: message`; mhs stops at the first error, so the next one shows after that one is fixed.

### miso lint

```
miso lint [ARGS...]
```

Runs [hlint](https://github.com/ndmitchell/hlint) on the source dirs of `miso.yml` with `ARGS` (hlint reads `.hlint.yaml`), and exits with hlint's status. Fails when hlint is not installed.

### miso repl

```
miso repl
```

MicroHs, interactively. In a project, with its source dirs and `mhs-options`, after installing its dependencies: `import` a module of the project to use it. Outside a project, with the packages that come with the tool. When the input is not a terminal it reads plain lines, so expressions can be piped to it. `:quit` leaves; `:help` lists the other commands.

### miso clean

```
miso clean
```

Removes what builds make in the project: `dist/`, `public/`, `.miso/` (installed packages), `.mhscache`, `dist-mcabal/` and `.miso-build.log`. It fails outside a project, so that it does not remove another kind of project's `public/` or `dist/`.