CLI Reference

1. Execution

sno run <file.sno>

Run a program via the interpreter. The default execution mode.

sno run hello.sno

sno jit <file.sno>

JIT-compile and run via Cranelift. Typically 3× faster than the interpreter for compute-heavy programs.

sno jit factorial.sno

sno eval "<expr>"

Evaluate a single expression and print the result. Useful for quick calculations.

sno eval "6 * 7"
sno eval "[1..10] |> filter (\x -> x % 2 == 0) |> sum"

sno watch run <file.sno>

Watch the file for changes and automatically re-run on every save.

sno watch run hello.sno

sno run --untrusted <file.sno>

Sandbox mode for LLM-generated code. Rejects run/jit backends; forces the WASM path. Use this when running code you did not write.

sno run --untrusted generated.sno
sno jit --untrusted generated.sno   # error — use sno wasm for untrusted code

Error output formats

Control how diagnostics are emitted. The JSON formats are LSP-compatible and consumed by editors and agents.

sno --errors json run file.sno          # LSP-compatible JSON (range + hint + related[])
sno --errors json-legacy run file.sno   # Legacy flat JSON (span + llm_hint + notes[])

2. Compilation

sno build <file.sno>

Compile to Synoema bytecode.

sno build quicksort.sno

sno build --native <file.sno> -o <out>

AOT-compile to a native binary for the host platform.

sno build --native factorial.sno -o factorial
./factorial

sno build --native --emit obj <file.sno>

Emit a raw .o object file to stdout. Useful for linking into larger projects.

sno build --native --emit obj factorial.sno > factorial.o
gcc factorial.o -o factorial

sno build --native --emit ir <file.sno>

Emit Cranelift IR for inspection or debugging.

sno build --native --emit ir factorial.sno

sno build --native --target aarch64-linux --emit obj <file.sno>

Cross-compile to AArch64 Linux ELF. Link manually with a cross-linker.

sno build --native --target aarch64-linux --emit obj factorial.sno -o factorial.o
aarch64-linux-gnu-gcc factorial.o -o factorial-arm64

sno wasm <file.sno>

Compile to WebAssembly (.wasm). Required for IoT Tier 0 targets and for untrusted code execution.

sno wasm factorial.sno           # emits factorial.wasm
sno wasm rule_fan_control.sno   # IoT rule → WASM artifact

3. Analysis

sno check <file.sno>

Parse and typecheck without running. Fast — use this in CI or before committing.

sno check quicksort.sno

sno verify <file.sno>

Typecheck, run with a timeout, and emit a JSON report. Useful for automated verification pipelines.

sno verify quicksort.sno

sno fmt <file.sno>

Format a source file in-place. The formatter is deterministic and idempotent.

sno fmt quicksort.sno

sno fmt <dir> --check

Dry-run formatting check. Exits non-zero if any file would be changed. Use in CI.

sno fmt src/ --check

sno doc <file.sno>

Generate HTML documentation from doc-comments and type signatures.

sno doc quicksort.sno

sno doc --contracts <file.sno>

Emit a compact table of all requires/ensures contracts in the file.

sno doc --contracts rule_pump.sno

sno changelog <old.sno> <new.sno>

Diff the public API between two versions of a module. Reports type changes and contract changes.

sno changelog lib_v1.sno lib_v2.sno

sno graph <dir> [--format dot|json]

Visualize the module import dependency graph. Outputs DOT (for Graphviz) or JSON.

sno graph src/
sno graph src/ --format dot | dot -Tsvg -o deps.svg

sno constrain

Read Synoema source from stdin and emit a type-constrained token mask as JSON. Used by the constrained decoding pipeline for LLM inference.

echo "add x y = " | sno constrain

sno test <dir>

Discover and run all doctests under a directory.

sno test examples/

4. Package Management

sno pkg list [--json]

List all installed packages from ~/.sno/packages/ with compatibility status.

sno pkg list
sno pkg list --json

sno pkg add <name[@ver]|./path|https://url>

Install a package from the registry, a local directory, or a URL. Resolves transitive dependencies (depth 16).

sno pkg add sno-http             # latest from registry
sno pkg add sno-http@1.2.0      # pinned version
sno pkg add ./my-local-pkg      # from local path
sno pkg add https://example.com/pkg.tar.gz

sno pkg remove <name>

Remove an installed package from ~/.sno/packages/.

sno pkg remove sno-http

sno pkg search <query>

Full-text search of the registry by name, description, and keywords.

sno pkg search http
sno pkg search "json parsing"

sno pkg login [--key KEY]

Authenticate with the registry. Opens a browser for OAuth if --key is omitted. Saves the API key to ~/.sno/config.toml.

sno pkg login
sno pkg login --key sno_abc123

sno publish

Publish the current package to the registry. Run from the package directory. Performs a typecheck and binary scan before upload.

cd my-package/
sno publish

sno pkg run <name> [-- <args>]

Run a package’s binary entry point (defined via bin in sno.toml).

sno pkg run sno-http -- --port 8080

5. Project & Setup

sno new <name> [--template ...]

Scaffold a new project. Available templates: default, library, mcp-tool, cli-app.

sno new myapp
sno new mylib --template library
sno new my-mcp-tool --template mcp-tool

sno init <name>

Alias for sno new. Kept for backward compatibility.

sno init myapp

sno install

Install the sno and synoema binaries to ~/.sno/bin/ and add them to PATH.

sno install
sno install --with-rag   # also download the RAG pack

sno doctor [--output json] [--fix]

Check installation health: binary version, PATH, GBNF, RAG pack status. Use --fix to automatically repair common issues.

sno doctor
sno doctor --output json
sno doctor --fix

sno update [--check] [--rollback]

Self-update the sno binary to the latest release. Use --check to check without applying, --rollback to revert.

sno update
sno update --check
sno update --rollback

sno setup claude|cursor|all [--binary] [--dry-run]

Configure MCP integration for Claude Desktop, Cursor, or both. Use --binary to use the pre-built binary instead of building from source.

sno setup claude --binary
sno setup cursor --binary
sno setup all --dry-run        # preview without writing
sno setup claude --with-rag   # also download RAG pack

sno config list|get|set|edit|reset

Manage ~/.sno/config.toml. Use edit to open in $EDITOR, reset to restore defaults.

sno config list
sno config get rag.auto_inject.enabled
sno config set rag.auto_inject.enabled true
sno config edit
sno config reset

sno migrate [path] [--dry-run] [--list]

Migrate .sno source files to the current syntax. Use --dry-run to preview, --list to show what would be changed.

sno migrate src/
sno migrate src/ --dry-run
sno migrate src/ --list

sno bump patch|minor|major

Bump the project version in sno.toml and propagate to every @version annotation across .sno files. Pass --check to print the current version without changes.

sno bump patch                # 0.1.0 -> 0.1.1
sno bump minor                # 0.1.1 -> 0.2.0
sno bump --check              # print current

sno install-hooks

Install the pre-commit hook at .git/hooks/pre-commit for the T1 doc-coherence check. Recommended for any repo with public functions.

sno install-hooks

6.5. Doc-Coherence & Refactor Sessions

The doc-coherence ratchet (RULES §9 in the language repo) blocks PRs that introduce new violations of "every public function has ---". Refactor sessions are temporary exemptions.

sno health [--format text|json] [--scope all|sessions|violations|deferred|coverage]

Project-wide doc-coherence health report. Counts undocumented public decls, active refactor sessions, and deferred violations. Use --format json for CI integration.

sno health
sno health --format json
sno health --scope violations

sno ratchet check [--base <ref>] [--head <ref>] [--format text|json]

CI gate: fail the build if HEAD introduces new hard violations vs. --base. Used in the T1 ratchet workflow.

sno ratchet check                              # base = main, head = HEAD
sno ratchet check --base origin/beta-1 --head HEAD --format json

sno normalize [path] [--dry-run] [--audience human|llm|both]

Insert anchor stubs (--- placeholders) for every undocumented public declaration. Combine with --audience llm to seed the LLM-targeted doc set.

sno normalize src/ --dry-run
sno normalize . --audience both

sno update-docs [path] [--dry-run]

Refresh the standard LLM doc bundle (docs/llm/synoema.md + stdlib-*.md) inside an existing project. Triggered automatically by sno doctor --fix when llm_docs is stale.

sno update-docs .
sno update-docs ./project --dry-run

sno refactor start <id> --scope "<glob>" --stages "<s1>,<s2>"

Open a refactor session: a doc-coherence ratchet exemption tied to a glob and a list of stages. The session records HEAD SHA on each advance so reviewers can see exactly what changed in each phase.

sno refactor start typer-rewrite --scope "lang/crates/synoema-types/**" --stages "core,desugar,callsites"
sno refactor advance --stage desugar
sno refactor list                                  # all sessions
sno refactor list --status active
sno refactor finish typer-rewrite                  # close session
sno refactor abandon typer-rewrite                 # close without success

6. Skills

Skills are reusable task templates for LLM agents, stored as SKILL.md files. The runtime discovers them from three directories: workspace, ~/.sno/skills/, and the bundled library (11 built-in skills).

sno skill list

List all available skills: workspace, user-global, and bundled.

sno skill list

sno skill install <path>

Install a skill from a local path or file:// URI to ~/.sno/skills/.

sno skill install ./my-skill/SKILL.md
sno skill install file:///path/to/skill/

sno skill remove <name>

Remove a skill from the workspace or user-global skill directory.

sno skill remove my-skill

7. MCP & RAG

sno mcp-install [--from-source] [--local <path>]

Install the Synoema MCP server binary to ~/.sno/bin/. Auto-detects a local build if present.

sno mcp-install
sno mcp-install --from-source        # build from source
sno mcp-install --local ./my-build  # copy pre-built binary

sno mcp-update

Update the MCP server to the latest version.

sno mcp-update

sno rag install [--version=<v>] [--model-only|--index-only]

Download, verify (SHA-256), and activate a RAG pack from synoema.tech/rag/. The pack includes an ONNX embedding model and a pre-built vector index.

sno rag install
sno rag install --version=0.1.0-beta.1
sno rag install --model-only
sno rag install --index-only

sno rag status [--output=json]

Report the state of the installed RAG pack: version, model path, index path, checksum.

sno rag status
sno rag status --output=json

sno rag update [--check|--dry-run]

Check for or apply a newer RAG pack.

sno rag update
sno rag update --check    # check only, do not download
sno rag update --dry-run  # simulate without writing

sno rag remove

Uninstall the RAG pack and remove model/index files from ~/.sno/models/.

sno rag remove

sno build-index --sources <csv> --output <dir> [...]

Build a RAG vector index offline from local sources. Useful for custom corpora or air-gapped environments.

sno build-index \
  --sources corpus.jsonl,docs/,skills/ \
  --output ~/.sno/index/custom \
  --model ~/.sno/models/embed/current \
  --chunk-strategy auto \
  --batch-size 64 \
  --include-scopes corpus,docs,skills,sno,traces

Flags: --chunk-strategy auto|jsonl|md|skill|sno|trace, --batch-size N, --dry-run, --force, --include-scopes

sno fix <file.sno> [--max-turns N] [--dry-run] [--with-rag]

Run the ReAct inline agent to automatically fix type errors and diagnostics in a file. Requires Python ≥3.9.

sno fix broken.sno
sno fix broken.sno --max-turns 5
sno fix broken.sno --dry-run           # preview diff, do not write
sno fix broken.sno --with-rag          # enable RAG retrieval in the agent
sno fix broken.sno --with-rag --top-k 8

8. IoT / Fleet

sno fleet server [--port N] [--db PATH]

Start the IoT fleet management server. Provides OTA update delivery, device registry, and health monitoring.

sno fleet server
sno fleet server --port 9000 --db /var/sno/fleet.db

sno fleet devices [--fleet-url URL]

List all devices registered with the fleet server.

sno fleet devices
sno fleet devices --fleet-url http://fleet.example.com:9000

sno fleet status [--fleet-url URL]

Print a fleet health summary: device count, online/offline ratio, last seen timestamps.

sno fleet status
sno fleet status --fleet-url http://fleet.example.com:9000

Notes

All commands accept --help for a quick usage summary. For LSP-compatible JSON error output, prefix any command with --errors json.