The miso CLI
Overview
miso is one binary that creates, builds, runs and serves miso applications. It has MicroHs (mhs) and 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 shell:
$ curl -fsSL https://haskell-miso.org/download | sh
The installer downloads the release for your OS and architecture from haskell-miso/cli, 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
$ 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.
Requirements
- A C compiler (
cc): mhs compiles programs to C. - For the browser targets (
browser,browser_js), emscripten (emcc). curl,tar,sha256sumorshasum, andgitfor git dependencies.- hlint, for
miso lintonly.
On Windows, install the tools in MSYS2 first: pacman -S gcc make tar curl git.
Every command
| Command | What it does |
|---|---|
miso new NAME | a new project from a template |
miso templates | list the templates |
miso init | make the current directory a project |
miso build [NAME...] | build the project, or the programs named |
miso run [NAME] [ARGS] | build a native program and run it |
miso test [NAME...] | build the tests and run them |
miso dev [NAME] | build, serve, and rebuild and reload on every change |
miso serve | serve public/ as it is |
miso watch [NAME] | type check on every change, and show the first error |
miso lint [ARGS] | run hlint on the sources |
miso repl | MicroHs, interactively, with the project's modules |
miso clean | remove what builds make |
miso install | install the dependencies of miso.yml |
miso add PKG... | add Hackage packages, and install them |
miso remove PKG... | remove dependencies |
miso list | the installed packages |
miso lock | write miso.lock |
miso update | lock again at the newest versions, and install |
miso vendor | copy the locked sources to vendor/ |
miso cabal | print the .cabal file of the library |
miso doctor | check the installation and the tools |
miso upgrade [VERSION] | install the latest release, or VERSION |
miso uninstall | remove miso |
miso version | the versions of miso and MicroHs |
miso help | the commands |
miso mhs ARGS | the MicroHs compiler built into the tool |
miso mcabal ARGS | MicroCabal, compiling with miso mhs |
Conventions
- Commands that work on a project read
miso.ymlin the current directory (not a parent), and fail without one. The others arenew,templates,init,serve,repl,listand the commands of the tool itself. ==>lines say what miso is doing or has done,->lines are steps of it;warning:anderror:go to standard error.NO_COLOR=1turns colors off.- The exit status is 0 when the command worked and 1 when it failed.
miso runandmiso lintexit 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 |
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 GitHub Action installs a release and builds and tests a project with it:
- uses: haskell-miso/setup-miso@main
with:
version: latest