The intentset command

intentset reads the records in a repository and reports on them. validate, graph, architecture check, impact and review execute nothing, reach no network and never change a record; publishing and serving are separate commands you run on purpose.

Install

npm install --save-dev @intentset/cli
npx intentset validate

pnpm add --save-dev @intentset/cli
pnpm exec intentset validate

The checks that read source (architecture check, validate at L2 and above, review) need TypeScript 7, the CLI's peer dependency; the rest of the toolchain does not. npm installs the peer beside the CLI; pnpm gives the CLI the TypeScript your repository has, and on one earlier than 7 those checks stop and name the version found. There, run the toolchain without installing it: pnpm dlx --package=@intentset/cli --package=typescript@7 intentset, or npx -p @intentset/cli -p typescript@7 intentset.

In a repository

init writes the configuration, empty registries and the agent guide your agents follow. From then on, CI runs these on every change, and an agent runs them before it finishes:

intentset validate --level L2
intentset review --base origin/main --fail-on-drift

validate runs every check the level asks for. Each level includes those below it: L1 is the model, L2 adds the architecture, L3 the evidence and L4 publication readiness. review adds the impact of what changed, and lists each slice whose code changed while its records did not.

Every command

This is the command's own help, as intentset --help prints it.

usage: intentset <command> [options]

commands
  init [--repository <name>] [--example] [--agents]
                            create .intentset/config.yaml, an empty .intentset/registries.yaml
                            and .intentset/agents.md, the guide that tells coding agents how to
                            keep the model current; --example adds the scheduling example under
                            product/scheduling/; --agents writes only the guide, for a
                            repository already initialized. Never overwrites a file.
  guide                     print that guide for this repository, for the scope its config
                            names, without writing anything
  validate                  every check the level asks for; exit 1 when any diagnostic is an
                            error
  graph [--format json] [--include-bodies] [--release <product>:<label>] [--out <file>]
        [--generated-at <time>] [--report evidence|knowledge|impact|ownership|all]...
        [--include-restricted]
                            print the intentset/export/0.4 envelope, or write it to --out;
                            each --report adds a section (ownership needs L2, evidence L3; all
                            is every one the level reads). Restricted artifacts are withheld
                            and counted unless --include-restricted
  architecture check [--mode migration|strict] [--baseline <file>] [--write-baseline <file>]
                            ownership, claims, imports, layers and regions (default level L2)
  evidence import --from vitest|playwright|node-tap <report> --out <file> --product <ID>
        --release <label>
        [--environment <text>] [--started-at <time>] [--finished-at <time>] [--uri-base <uri>]
        [--tool-version <v>]
                            turn a test report into run records bound to this commit and graph
  evidence stale [--release <product>:<label>] [--check] [--binding <subject|commit>]
        [--format list|json|playwright|vitest|node-test]
                            what needs a run: the automated verifications whose evidence is
                            not a current pass, as a table, as JSON, or as the arguments that
                            make a test runner run only those tests; never writes; --check
                            exits 1 when any needs a run
  impact <ID>               what depends on an artifact: direct, candidates, review context,
                            ancestors
  context <ID|path> [--include-restricted]
                            the bounded engineering context of an artifact, with paths and
                            bodies; given a file a slice claims, the context of that slice
  review [--base <ref>] [--fail-on-drift] [--baseline <file> [--fail-on-baseline-growth]]
                            the local review report: checks, coverage, the impact of what
                            changed, and each slice whose code changed while its records did
                            not; --fail-on-drift exits 1 for any such slice no commit
                            acknowledged with an Intentset-Unchanged trailer. With --baseline,
                            the entries the base's copy did not hold and those it retired;
                            --fail-on-baseline-growth exits 1 for any it did not hold
  publish --visibility <v> --audience <a> --product <ID> --release <r> --role <r> --edition <e>
        [--flag <f>]... [--authorized-internal] [--authorized-restricted] --out <dir> [--html]
        [--published-at <time>]
                            reviewed knowledge for one audience and release, as Markset with
                            provenance
  serve [--port <n>] [--host <address>] [--out <dir>]
                            the Atlas, the internal review pages, on http://127.0.0.1:3000/
                            (rebuilt when a file changes), or written to --out; runs at L2, or
                            L3 with run records
  migrate --to 0.2 [--allow-dirty]
                            move the records the model reads from specifications 0.1 to 0.2:
                            rewrites intentset.spec and intentset.profile in each record's
                            frontmatter and nothing else, and says how many. Refuses a tree
                            with uncommitted changes to tracked files unless --allow-dirty
  mcp --mode engineering [--include-restricted]
  mcp --mode customer --visibility <public|customer> --audience <a> --product <ID>
        --release <r> --role <r> --edition <e> [--flag <f>]...
                            the read-only MCP server on stdio: the engineering graph, or one
                            publication made in memory as publish makes it, and nothing else

options
  --root <dir>              repository root (default: the nearest directory at or above this
                            one holding .intentset/config.yaml)
  --json                    machine-readable output, keys in canonical order
  --carrier <markset|plain> how documents are read (default markset)
  --level <L1..L4>          conformance level; each includes those below it (default L1):
                            L2 adds architecture, L3 evidence, L4 publication readiness
  --evidence <file>         L3 and above: run records to read, repeatable (default: every
                            *.json in .intentset/evidence/, which holds local output and is not
                            committed)
  --product <ID> --release <label>
                            L3 and above: the exact scope evidence is assessed for (default:
                            every scope)
  --binding <subject|commit>
                            L3 and above, and evidence import: how run evidence is judged
                            current, overriding evidence.binding in the configuration (default:
                            subject where slices claim files, else commit). Subject keeps a
                            record current while what it checked is unchanged; commit only at
                            the commit it ran at
  --mode <migration|strict> --baseline <file>
                            L2 and above: whether a baseline of known violations applies, and
                            which (for mcp, --mode names the server's mode instead)
  -h, --help                show this help
  --version                 print "intentset <version>", the checker version a report names

exit codes: 0 no errors, 1 validation errors (or, with review --fail-on-drift,
            unacknowledged drift; with --fail-on-baseline-growth, a baseline
            entry the base did not hold), 2 invocation or tool failure

Exit codes

--json prints machine-readable output, with its keys in canonical order, for CI and for agents.