CLI

The selm command is your day-to-day toolbox: create a project, check types, build, run, test, and export docs. Run selm help or selm help <command> in the terminal; here is the full map.

Commands

selm init [PATH] [--server] [--database=postgres|sqlite] [--client]
selm gen database NAME [field:type ...]
selm gen migration NAME [--table=TABLE] [field:type ...]
selm check
selm deps
selm format [--check] [--stdin] [PATH...]
selm make [--optimize|--debug]
selm run [--sname NAME|--name NAME] [--cookie COOKIE]
selm serve [--sname NAME|--name NAME] [--cookie COOKIE]
selm dev [--sname NAME|--name NAME] [--cookie COOKIE]
selm console [--erl|--offline] [--no-init] [--no-boot] [--sname NAME|--name NAME] [--cookie COOKIE]
selm release [--include-erts] [--out=DIR]
selm export [--out=_site]
selm docs [--out=docs]
selm docs-gen [--out=site/src/Generated/StdlibCatalog.selm] [--stdlib=stdlib]
selm test [PATH[:line...]...]
selm self-test
selm bump
selm publish [--yes] [--replace]
selm device info | build | install | flash | watch | monitor | expand | erase
CommandWhat it does
initScaffold a project. Default is a Hello world. --server adds an HTTP app; --database=postgres|sqlite wires Repo (implies --server); --client adds a Browser SPA (implies --server).
gen databaseWrite src/database/Name.selm with an id primary key and optional field:type columns (Phoenix-style aliases like string / bool, or Selm types).
gen migrationWrite a dated plan under src/migrations/. With field:type args, pass --table= to emit ADD COLUMN SQL; without fields, a no-op stub.
checkTypecheck the project and print ok or the errors
depsResolve Hex deps, write selm.lock, fetch and compile packages
formatFormat .selm files. With --check, change nothing and exit non-zero if any file would change.
makeBuild for the configured target. JavaScript writes build/js/app.js. Erlang compiles for the BEAM and generates the schema.
runBuild, then run main (Erlang target). HTTP mains stay up; plain programs print and exit. Optional --sname / --name plus an explicit --cookie (or SELM_NODE / SELM_COOKIE / [distribution] cookie) for distribution — no default cookie.
serveLike run for HTTP apps, but also creates the local Postgres database if needed and waits for port 3000 (Erlang target). Same distribution flags as run.
devWatch sources and rebuild. Erlang reloads the running node, or restarts it when a load will not stick. An open page refreshes when the UI bundle hash changes. JavaScript serves the project on port 3000 and refreshes the same way. AtomVM uses selm device watch.
consoleSelm expression REPL on the project node (attach or boot). --erl for Erlang remsh; --offline for a local REPL; --no-init / --no-boot to skip project preload or auto-boot
releaseBuild an OTP release under build/prod/rel/<name>/ (boot script plus bin/<name>). Needs name / version in selm.toml and a long-running main. Start with SELM_COOKIE set. --include-erts bundles Erlang.
exportBuild, then write Site.pages as HTML and optional Site.files as raw text (RSS). Files in static/ are copied alongside.
docsWrite HTML from {-| -} comments into docs/, in the stdlib layout. selm publish uploads that site to Hexdocs.
docs-genRegenerate site/src/Generated/StdlibCatalog.selm from stdlib/*.selm
testCompile and run suites under tests/
self-testCompiler fixture checks plus an end-to-end session/API smoke test
bumpSet version in selm.toml from an Elm-style API diff against the latest Hex release (PATCH / MINOR / MAJOR).
publishCheck a library and upload it to Hex with docs. Verifies the version bump against the prior exposed API unless --replace.
deviceBuild, install, flash, watch, and monitor an AtomVM board. expand and erase are ESP32 only. watch rebuilds and reflashes when sources change.

selm dev takes the same --sname, --name, and --cookie flags as selm serve. Editing a handler shows up on the next request. Changing which function main passes to Server.serve, or changing the supervision tree or socket mounts, restarts the BEAM node, and in-memory process state starts over. A page reloads only when the UI bundle changes, so client state stays put across server-only edits.

Targets

In selm.toml, target is "erlang" (default), "javascript", or "atomvm". Pick the one that matches what you are building.

Erlang builds servers, database modules, and server-rendered HTML. JavaScript builds browser apps with Elm 0.19.3-compatible output. Migration modules, erlang/elixir FFI, and := are rejected on JS; database modules project to types plus JSON codecs. [glsl| … |] works on JS for WebGL (elm-explorations/webgl), not on BEAM or AtomVM. OR-patterns, guards, and record/tuple value patterns are allowed on both; see From Elm.

AtomVM builds one console program with Device.program. Set [atomvm] family to rp2 or esp32 and a board such as pico or esp32. Optional crash_retries defaults to 3 (or "infinity"). selm device build writes build/dev/atomvm/app.avm (and app.uf2 for RP2). Pass --port when more than one serial device is connected.

selm device watch rebuilds the app and runs the same flash path whenever project sources change (host rebuild + reflash, not in-place code load). ESP32 is the automated path: each change writes app.avm over serial with no BOOTSEL remount. RP2 is best-effort; you may need to remount the UF2 volume between flashes. Build or flash errors are logged and watching continues.

# Erlang (default)
target = "erlang"

# JavaScript Browser app
target = "javascript"
source-directories = ["src"]

JavaScript apps get Browser, Html, Http, Json.Decode, and the rest of the Elm-compatible client platform without any [dependencies]. List only community Elm packages there, such as "elm-explorations/webgl" = "1.1.3".

An Erlang project can also set [client].entry to a .selm Browser app; selm make builds it next to the server.

Project layout

A typical full-stack Erlang app looks like examples/03_todo_app:

selm.toml                 # target, source-directories, client.entry, deps
elm.json                  # generated: client source-directories
src/server/*.selm         # HTTP + supervisors
src/database/*.selm       # tables and transactional APIs
src/migrations/*.selm     # ordered migration plans
src/cli/**/*.selm         # Mix-style CLI tasks (CLI.*)
src/client/*.selm         # Browser.application SPA
build/dev/erlang/              # generated + runtime BEAM
build/dev/erlang/ebin/<name>.app
build/dev/erlang/lib/<app>-<vsn>/
build/dev/schema.sql           # CREATE DDL fallback
build/dev/models.json          # desired schema models
build/dev/migrations/plans.json
build/prod/rel/<name>/        # after selm release
build/client/app.js            # SPA after selm make ([client].entry)
build/client/app.hash          # cache-bust hash for Server.asset
build/js/app.js                # after selm make (javascript target)

Custom CLI tasks

Modules under CLI.* that expose run : List String -> a become selm subcommands (CLI.Increment → selm increment). Use stdlib Req when a task should call your HTTP server instead of shelling out to curl. See examples/02_counter/src/cli/.