Snag · open-core CLI

CLI reference

Every command, flag, and environment variable the snag CLI accepts. New here? Start with the getting-started guide; for keys and providers see setting up providers.

Install

npm install -g @snag-run/cli
snag --help

# …or run without installing:
npx @snag-run/cli --help

Requires Node.js ≥ 20.

Commands

Command	What it maps
`snag map <arg>`	Auto-resolves: a `.md`/`.txt` doc → spec, a code file → module, a bare name → capability.
`snag map spec <path>`	A spec / PRD document.
`snag map module <path>`	Existing code you point at (a file).
`snag map capability "<name>"`	A behavior by name — the agent discovers the relevant files itself.
`snag map validate <file>`	Validate a Snag Map JSON file against the schema (read-only; no LLM call).
`snag view [map]`	Open the local read-only viewer (all maps, or one); port `7624` by default.
`snag skills install`	Install the `snag-map` agent skill into `~/.agents/skills` (symlinked into `~/.claude` and `~/.codex`).
`snag --version`	Print the CLI version, then exit (`-V`).

Each run writes a timestamped JSON snapshot under .snag/maps/<mirrored-path>/. The maps are meant to be committed — diffs across snapshots show how a change's failure surface moves over time.

When you regenerate a map for a source that already has a committed snapshot, snag reconciles the new run against the most recent prior map: unchanged failure modes carry their existing node ids forward, so the committed history stays low-churn and a diff shows real movement (a mode added, removed, or re-scored) rather than every id reshuffling. It's automatic and best-effort — there's no flag to manage, and any hiccup falls back to the raw generated map.

Flags · `snag map`

These apply to snag map and its spec / module / capability subcommands.

Flag	Value	Default	Description
`--adapter <a>`	`anthropic` · `openai` · `openrouter`	`anthropic`	Provider adapter. Precedence: flag › `SNAG_ADAPTER` env › default.
`--model <m>`	model id	`claude-sonnet-4-6` (anthropic)	Model id. Precedence: flag › `SNAG_MODEL` env › adapter default. Required for `openai` / `openrouter` (no default).
`--max-steps <n>`	integer 1–100	`25`	Agentic code-scan step ceiling — a liveness bound, not a spend cap. Out-of-range values are clamped.
`--temperature <n>`	number 0–2	`1`	Sampling temperature. Precedence: flag › `SNAG_TEMPERATURE` env › default. Ignored for OpenAI reasoning models (`gpt-5.x` / `o-series`), which reject an explicit temperature.
`--max-output-tokens <n>`	integer 1–200000	`16000`	Output-token budget for the model's response. Precedence: flag › `SNAG_MAX_OUTPUT_TOKENS` env › default.
`--harness <name>`	`snag` · `claude-code` · `codex`	`snag`	Harness provenance — stamped into `meta.harness` for observability. Precedence: flag › `SNAG_HARNESS` env › default.
`-v`, `--verbose`	—	—	Set both the `cli` and `engine` log components to `verbose`.
`-q`, `--quiet`	—	—	Set both components to `quiet` (errors only).
`--log <comp>=<level>`	`cli`\|`engine` = `quiet`\|`normal`\|`verbose`	cli=normal, engine=quiet	Per-component log level (comma-separate to set both). Aliases: `error`/`info`/`debug`. Precedence: this flag › `-v`/`-q` › `SNAG_LOG` env › defaults.
`--help`, `-h`	—	—	Print `snag map` usage and exit.

All harness logging goes to stderr; stdout stays clean (Wrote Snag Map: <path> only), so it's safe to pipe.

Flags · `snag view`

Flag	Value	Default	Description
`--port <n>`, `-p`	integer 0–65535	`7624`	Port to serve on. Precedence: flag › `SNAG_VIEW_PORT` env › default. On the default port snag walks up to the next free one if `7624` is busy; an explicit `--port` that's in use is a fatal error.

The viewer serves read-only over 127.0.0.1. Pass a [map] path to deep-link one map; omit it for an index of every committed map.

Environment variables

Where a flag exists, the flag wins over the matching variable. Provider keys and settings are covered in depth on the providers page.

Variable	Purpose
`SNAG_API_KEY`	Provider key, consulted before any adapter-specific key.
`ANTHROPIC_API_KEY` `OPENAI_API_KEY` `OPENROUTER_API_KEY`	Per-adapter key fallback (used when `SNAG_API_KEY` is unset).
`SNAG_ADAPTER`	Provider adapter (`anthropic` · `openai` · `openrouter`).
`SNAG_MODEL`	Model id.
`SNAG_API_URL`	Base URL for the active adapter (passthrough + stamped into `meta.apiUrl`); wins over the per-adapter URL var.
`ANTHROPIC_API_URL` `OPENAI_API_URL` `OPENROUTER_API_URL`	Per-adapter base-URL override (used when `SNAG_API_URL` is unset).
`SNAG_TEMPERATURE`	Sampling temperature (0–2); out-of-range is treated as unset.
`SNAG_MAX_OUTPUT_TOKENS`	Output-token budget (1–200000, default 16000).
`SNAG_HARNESS`	Harness provenance (`snag` · `claude-code` · `codex`) stamped into `meta.harness`.
`SNAG_PROVIDER_NAME`	Vendor label stamped into `meta.providerName` (observability).
`SNAG_LOG`	Log config — e.g. `debug`, or `cli:verbose,engine:quiet`.
`SNAG_VIEW_PORT`	Default port for `snag view`.

@snag-run/cli on npm dave@teeang.net