@snag-run/cli
The snag CLI brings in and views Snag Maps — a Happy Path → Failure Map for
a PRD, spec, or change. Snag applies FMEA-style reasoning (the discipline behind
failure analysis in aerospace and manufacturing) to a document or some code and
surfaces the failure modes a normal review tends to miss, as an interactive graph
you can commit to git and review like any other artifact.
The map itself is generated by a coding-agent skill running inside your own
coding agent (Claude Code, Codex, …), which emits a failure-map/v1 JSON. The
CLI is key-free: it holds no provider API key and makes no LLM call. It
ingests that JSON, validates it, serves the local viewer, and (optionally) pushes
a committed map to a backend with your own bearer token.
Final release from the monorepo.
0.4.0is the last@snag-run/clipublished from thesnagrepo; development now continues at github.com/snag-run/snag-cli, whose README records why snag stopped as a product. snag was wound down after an uncertain ICP and a pre-registered experiment showed a plain skill approach held most of the value (see the snag-fmea skill). This CLI remains a working, key-free map toolchain.
Docs & live demo: snag.run — the getting-started guide and the CLI reference, plus interactive example maps.
Install
npm install -g @snag-run/cli
# then just call it by name:
snag --help
# or run without installing:
npx @snag-run/cli --help
Requires Node.js >= 20.
Quickstart
# 1. In your coding agent, run a map-generating skill over a PRD, a file, or a
# named capability. It uses the agent's own read-only tools to produce a
# failure-map/v1 JSON — no provider key configured in snag.
# 2. Bring that JSON in — snag validates it, derives the committed path from
# the map's own subject, and reconciles node ids against the prior snapshot:
snag map ingest path/to/skill-output.json
# → writes .snag/maps/<subject>/<timestamp>.json (commit this)
# 3. Open the interactive viewer
snag view
# → serves a read-only map browser at http://localhost:7624
# (omit the map arg for an index of every committed map)
Each source subject becomes a folder under .snag/maps/, holding one timestamped
JSON snapshot per run. The maps are meant to be committed — diffs across
snapshots show how a change's failure surface moves over time, and the map travels
with the code in review.
When you ingest a map for a subject 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. The skill proposes, reconcile disposes, git records the delta.
Use it inside your coding agent
Map generation runs as an agent skill inside a coding agent (Claude Code, Codex,
…): it produces a Snag Map over the current diff / a file / a named capability
using the agent's own read-only tools, so generation rides your existing
coding-agent subscription and no provider key ever lives in snag. The skill
emits a failure-map/v1 JSON and self-checks it with snag map validate before
you snag map ingest it.
Migrating from 0.2.x
The CLI is now key-free — the built-in map generator and all provider-key
configuration have been removed. If you generated maps on 0.2.x by pointing a
provider key at the CLI, switch to the skill flow: generate the map inside your
coding agent with a map-generating skill, then bring it in with snag map ingest. SNAG_API_KEY is now a backend bearer token
for snag push, not a model-provider key. snag view and snag map validate
are unchanged.
Commands
| Command | What it does |
|---|---|
snag map ingest <json> |
Bring a skill-emitted failure-map/v1 JSON into .snag/maps/ — validates, derives the flat path from the map's subject, and reconciles node ids against the committed prior (key-free, offline; no LLM). |
snag map validate <file> |
Validate a Snag Map JSON file against the schema and report soft-lint warnings (read-only; no write, no LLM). |
snag push <subject> |
Push the newest committed map for a path subject to the backend as an owned Snapshot (see Pushing to a backend). |
snag push capability "<name>" |
Push the newest committed map for a capability, grouped by its typed name rather than its discovered files. |
snag view [map] |
Open the local read-only viewer (all maps, or one); port 7624 by default. |
snag --version |
Print the CLI version (-V). |
Flags
snag view
| Flag | Value | Default | Description |
|---|---|---|---|
--port <n>, -p <n> |
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 (GET /, plus a small JSON API the
browser bundle calls). Pass a [map] path (repo-relative or maps-relative) to
deep-link one map; omit it for an index of every committed map.
snag push
| Flag | Value | Description |
|---|---|---|
--insecure |
— | Allow sending the bearer token over plaintext http:// to a remote host (also SNAG_ALLOW_HTTP=1). Off by default — https-only, so the backend can't leak the key. |
The snag map subcommands tolerate (and ignore) the global -v / -q / --log
logging flags for muscle-memory compatibility.
Pushing to a backend
snag push uploads the newest committed map for a subject to a Snag backend as
a private, owner-only Snapshot. It authenticates with a bearer token — this is a
backend credential, not a model-provider key:
export SNAG_API_KEY=... # backend bearer token
snag push docs/prd/checkout.md # push newest committed map for a subject
snag push capability "checkout flow" # push a capability by typed name
The backend URL defaults to https://snag.run; override it with SNAG_BACKEND_URL.
The bearer token is sent over https:// only — pushing to a plaintext http://
remote is refused unless you pass --insecure (or set SNAG_ALLOW_HTTP=1), which
you'd only want for a local backend.
Environment variables
| Variable | Purpose |
|---|---|
SNAG_API_KEY |
Backend bearer token for snag push. Not a model-provider key — the CLI makes no LLM call. |
SNAG_BACKEND_URL |
Backend base URL for snag push (default https://snag.run). |
SNAG_ALLOW_HTTP |
Set to 1/true to allow the bearer token over plaintext http:// (same as --insecure). |
SNAG_VIEW_PORT |
Default port for snag view. |
SNAG_LOG |
Log config — e.g. debug, or cli:verbose,engine:quiet. |
In every case the matching command-line flag, when present, takes precedence over the environment variable.
Links
- Website & live demo — snag.run
- Full documentation — snag.run/docs
- npm — @snag-run/cli
License
Apache-2.0 David Taing. See LICENSE.