Command line

$ soma --help
The Soma language — fractal, declarative, agent-native

Soma is a language where every system is a cell: state, interface, lifecycle,
and distribution — in one model, from function to datacenter.

Quick start:
  soma init myapp && cd myapp
  soma serve app.cell            # HTTP on :8080
  soma check app.cell            # verify contracts
  soma verify app.cell           # prove state machines

Cluster (same code, multiple nodes):
  soma serve app.cell -p 8080
  soma serve app.cell -p 8081 --join localhost:8082

For coding agents:
  soma docs agent                # the language, offline, for your context
  soma describe --builtins --json   # exact signatures — never guess
  soma example invariant state_machine    # verified programs to start from

Docs: https://soma-lang.dev   (agents: https://soma-lang.dev/llms-full.txt)
Paper: https://soma-lang.dev/paper

Usage: soma-v3.2.4 [OPTIONS] <COMMAND>

Commands:
  run       Run a handler: soma run app.cell [args]
  serve     Start HTTP server: soma serve app.cell [-p 8080] [--join host:port]
  check     Check contracts, properties, and scale coherence
  lint      Lint for anti-patterns and suggest improvements
  fix       Auto-fix common errors found by check
  verify    Prove state machines, temporal logic, CAP properties, quorum
  test      Run test assertions in a .cell file. Storage is isolated: every memory slot uses a fresh in-memory backend, so runs never touch persistent state and always start clean. Supports `assert expr`, `assert_fails expr` (passes when expr errors), and `property`
  replay    V1: replay a .somalog file deterministically and report divergences
  describe  Describe a cell as structured JSON: signals, memory, state machines, scale, routes
  skeleton  Print a program as its skeleton: memory, state machines, and each signal's frame (reads / writes / moves / calls) — no handler bodies
  refs      Where a signal is declared, where its body is, and every call of it — program and tests — as file:line
  rename    Rename a signal everywhere it is written — declaration, body, calls, frames, tests — under the entry's directory
  holes     List the holes of a program's skeletons — signals with no body yet — in the order to fill them
  docs      Render generated reference docs: soma docs builtins
  fmt       Format .cell files to the canonical layout: soma fmt app.cell | soma fmt . --check
  eval      Grade a handler on a dataset: soma eval app.cell --handler classify --dataset cases.jsonl
  lsp       Language server over stdio: diagnostics on open / save, formatting
  explain   Explain a diagnostic code: soma explain E0028 (omit the code to list them)
  example   Find a verified example program: soma example invariant state_machine
  init      Create a new Soma project
  add       Add a dependency: soma add pkg --git url
  embed     Serve a program to a host process over stdin / stdout, one JSON object per line (the Python and TypeScript packages use it)
  tools     External tools (`tool … [mcp: "server"]` / `[openapi: "server/op"]`): pin their contracts in soma.lock
  install   Install all dependencies from soma.toml
  env       List installed packages
  repl      Start an interactive REPL
  props     List all registered properties and their rules
  deploy    Deploy to a cloud provider: soma deploy app.cell --target cloudflare
  build     Compile a .cell file and generate Rust code
  help      Print this message or the help of the given subcommand(s)

Options:
      --stdlib <STDLIB>
          Path to stdlib directory (default: auto-detect)

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Examples:
  soma serve app.cell                     Start web server
  soma serve app.cell --join host:8082    Join a cluster
  soma check app.cell --json              Errors as JSON (for agents)
  soma verify app.cell --json             Proofs as JSON (for agents)
  soma describe app.cell                  Cell structure as JSON
  soma run app.cell 42 "hello"            Execute a handler