# @snag-run/cli

> snag CLI — ingest, view, and push Snag Maps (Happy Path → Failure Map); key-free, offline, no LLM.

Latest version **0.4.0** (published 2026-07-08) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @snag-run/cli
pnpm add @snag-run/cli
yarn add @snag-run/cli
bun add @snag-run/cli
```

Provides the command `snag`.

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.4.0 |
| Published | 2026-07-08 |
| First published | 2026-06-25 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 3 |
| Unpacked size | 169 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | David Taing |
| Maintainers | teeang |
| Keywords | snag, fmea, failure-map, code-review, prd, cli |

## Links

- npm: https://www.npmjs.com/package/@snag-run/cli
- Repository: https://github.com/snag-run/snag
- Homepage: https://github.com/snag-run/snag/tree/main/packages/cli#readme
- Issues: https://github.com/snag-run/snag/issues
- npm.io page: https://npm.io/package/@snag-run/cli

## Dependencies (3)

- [escape-html](https://npm.io/package/escape-html.md) ^1.0.3
- [@snag-run/core](https://npm.io/package/@snag-run/core.md) ^0.4.0
- [@snag-run/renderer](https://npm.io/package/@snag-run/renderer.md) ^0.4.0

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 0.4.0 (latest) — 2026-07-08
- 0.3.0 — 2026-07-06
- 0.2.5 — 2026-07-05
- 0.2.4 — 2026-06-30
- 0.2.3 — 2026-06-26
- 0.2.2 — 2026-06-26
- 0.2.0 — 2026-06-25
- 0.1.1 — 2026-06-25
- 0.1.0 — 2026-06-25

## README

# @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](https://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](https://github.com/snag-run/snag-skills)).
> This CLI remains a working, key-free map toolchain.

**Docs & live demo: [snag.run](https://snag.run)** — the
[getting-started guide](https://snag.run/docs/getting-started) and the
[CLI reference](https://snag.run/docs/cli), plus interactive example maps.

## Install

```sh
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

```sh
# 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](#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:

```sh
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](https://snag.run)
- Full documentation — [snag.run/docs](https://snag.run/docs)
- npm — [@snag-run/cli](https://www.npmjs.com/package/@snag-run/cli)

## License

Apache-2.0 © David Taing. See [LICENSE](./LICENSE).

---
_Source: https://npm.io/package/@snag-run/cli · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
