npm.io
0.4.0 • Published 4 months agoCLI

@snag-run/cli

Licence
Apache-2.0
Version
0.4.0
Deps
3
Size
169 kB
Vulns
0
Weekly
0

@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.0 is the last @snag-run/cli published from the snag repo; 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.

License

Apache-2.0 David Taing. See LICENSE.

Keywords