CLI Reference¶

The stargraph CLI is a Typer app that drives engine execution, inspection, replay, and serve startup. It is bound via [project.scripts] in pyproject.toml:

[project.scripts]
stargraph = "stargraph.cli:main"

stargraph.cli.app registers the following subcommands:

Subcommand	Purpose
`run`	Compile and execute an IR graph end-to-end.
`compile`	Lower an authoring-format YAML to strict IR and print it.
`new`	Scaffold a graph from a template or shipped bundle.
`serve`	Boot the FastAPI app under uvicorn.
`inspect`	Read-only run inspector (timeline / state / facts).
`replay`	Counterfactual fork from a checkpoint + diff.
`respond`	Deliver a HITL response to an awaiting-input run.
`simulate`	Offline rule-firing trace against synthetic fixtures.
`counterfactual`	Compute a cf-derived `graph_hash` from a YAML mutation.
`model rollback`	Repoint a model-registry alias to the previous version.
`pack pin` / `pack revert`	Pin / un-pin a rule-pack version on a graph's governance mount.

The helper modules _inputs.py, _progress.py, _prompts.py, and _summary.py factor the interactive surface used by stargraph run (--inputs parsing, live progress rendering, HITL prompting, end-of-run summary). They are not user-facing entry points.

Plugin discovery tracing

Set STARGRAPH_TRACE_PLUGINS=1 (any non-empty value) before invoking any subcommand to log every plugin discovery, manifest validation, and registration step at INFO level via stargraph.plugin.loader. Use this when a tool, skill, store, or pack is "missing" -- the trace shows whether the distribution was discovered, whether its manifest validated, and at what order it registered.

`stargraph run`¶

Run a Stargraph graph end-to-end, or print its rule-firing trace without executing any node (--inspect).

Usage

stargraph run [OPTIONS] GRAPH

GRAPH is a path to an IR YAML file — or an authoring-format file (no ir_version key), which is compiled to IR transparently before the run. The file is parsed via yaml.safe_load, validated against IRDocument, and executed against a SQLite checkpointer (default: ./.stargraph/run.sqlite). The single-node loop drives to a terminal done / failed status; exit code is 0 on done, non-zero on failed.

Flag	Type	Default	Description
`--log-file PATH`	path	(none)	Append per-event JSONL records to this file.
`--checkpoint PATH`	path	`./.stargraph/run.sqlite`	SQLite checkpoint DB path.
`--inspect`	flag	`false`	Print rule-firing trace without executing nodes (FR-8/9).
`--inputs / -i K=V`	str (repeatable)	(empty)	Seed initial state field; key must match the IR `state_schema`.
`--quiet / -q`	flag	`false`	Suppress per-step progress output.
`--verbose / -v`	flag	`false`	Print tool result payloads inline.
`--no-summary`	flag	`false`	Skip end-of-run summary block.
`--summary-json`	flag	`false`	Emit summary as JSON instead of text.
`--non-interactive`	flag	`false`	Fail on `WaitingForInputEvent` instead of prompting.
`--lm-url URL`	str	(none)	LLM endpoint URL for DSPy nodes (OpenAI-compatible). Pair with `--lm-model`.
`--lm-model NAME`	str	(none)	LLM model identifier (e.g. `gpt-oss:20b`).
`--lm-key KEY`	str	`placeholder`	API key for the LLM endpoint (`placeholder` works for ollama).
`--lm-timeout SEC`	int	`60`	LLM call timeout in seconds.

--quiet and --verbose are mutually exclusive. --lm-url and --lm-model must be supplied together (or neither).

Examples

# Execute a graph with seeded state
stargraph run graphs/triage.yaml -i message="check pack drift" -i severity=3

# Dry-run: print rule-firing trace, no nodes executed
stargraph run graphs/triage.yaml --inspect

# Bind a local LLM for dspy nodes
stargraph run graphs/triage.yaml --lm-url http://localhost:11434 --lm-model gpt-oss:20b

See also: Concepts: IR, Replay, Counterfactual.

`stargraph compile`¶

Lower an authoring-format YAML to the strict IR and print it (learning/debug surface). An input that already declares ir_version is validated as IR and echoed back.

stargraph compile [OPTIONS] GRAPH

Flag	Description
`--show-clips`	Also print each generated rule as `rule-id: <CLIPS LHS> => goto X / halt`.

Shape errors exit 1 with an authoring:-prefixed message naming the offending key and the fix.

`stargraph new`¶

Scaffold a starting point; never overwrites an existing target.

stargraph new TEMPLATE [--dest PATH]

stargraph new research-bot writes research-bot.yaml — the authored react + judge feedback loop.
stargraph new <bundle> copies a shipped bundle's graph.yaml + SKILL.md into ./<bundle>/. Bundles: coding-agent, deep-research, evaluator-optimizer, hitl-approval, orchestrator-workers, rag-qa, triage-router.

`stargraph serve`¶

Boot the Stargraph FastAPI app under uvicorn (POC).

Usage

stargraph serve [OPTIONS]

Resolves the deployment profile via stargraph.serve.profiles.select_profile. When --profile cleared is selected, the cleared startup gate refuses --allow-pack-mutation and --allow-side-effects and exits non-zero with a ProfileViolationError (FR-32, FR-68, design §11.1, §15).

Flag	Type	Default	Description
`--profile NAME`	str	`oss-default`	Deployment profile (`oss-default` \| `cleared`). Forwarded via `STARGRAPH_PROFILE`.
`--host HOST`	str	`127.0.0.1`	Bind host for uvicorn.
`--port PORT`	int	`8000`	Bind port for uvicorn.
`--db PATH`	path	(per-process tmpfile)	SQLite checkpointer DB path.
`--audit-log PATH`	path	(none)	JSONL audit log path; passed to `RunHistory` for the event-offsets index.
`--allow-pack-mutation`	flag	`false`	Permit at-runtime Bosun pack mutation. Forbidden under `cleared`.
`--allow-side-effects`	flag	`false`	Permit `write` / `external` side effects. Forbidden under `cleared`.

Examples

# Local dev boot
stargraph serve --port 8000

# Cleared profile, with persistent checkpoint DB
stargraph serve --profile cleared --db /var/lib/stargraph/run.sqlite \
    --audit-log /var/log/stargraph/audit.jsonl

See also: Serve overview, Profiles, API.

`stargraph inspect`¶

Read-only run inspector. Three views over a SQLite checkpointer DB plus a Phase-1 legacy mode that streams raw JSONL events.

Usage

stargraph inspect RUN_ID --db PATH                  # timeline (default)
stargraph inspect RUN_ID --db PATH --step N         # state at step N
stargraph inspect RUN_ID --db PATH --diff N M       # CLIPS fact delta
stargraph inspect RUN_ID --log-file PATH            # legacy stream mode

Flag	Type	Default	Description
`RUN_ID`	str (arg)	req.	Run id to inspect (matches `event.run_id` and `checkpoint.run_id`).
`--db PATH`	path	(none)	SQLite Checkpointer DB. Required for timeline / state-at-step / fact-diff views.
`--log-file PATH`	path	(none)	JSONL audit log. With `--db`, enriches the timeline; without `--db`, streams events.
`--step N`	int (>= 0)	(none)	State-at-step view: print the IR-canonical state dict at step `N`.
`--diff N M`	int int	(none)	Fact-diff view: print CLIPS facts added/removed between step `N` and `M`.

The mode selector is --diff > --step > timeline. Both --diff and --step require --db. An empty filter result on the legacy stream mode is treated as a probable typo and exits non-zero (FR-6 force-loud).

Examples

# Timeline view of run, enriched with audit log
stargraph inspect 0193... --db .stargraph/run.sqlite --log-file run.jsonl

# Snapshot of state at step 7
stargraph inspect 0193... --db .stargraph/run.sqlite --step 7

# CLIPS facts asserted/retracted between step 5 and step 9
stargraph inspect 0193... --db .stargraph/run.sqlite --diff 5 9

`stargraph replay`¶

Fork a counterfactual run from any checkpoint and (optionally) render the parent-vs-cf RunDiff.

Usage

stargraph replay RUN_ID --db PATH [--mutation FILE.json]
                     [--from-step N] [--diff/--no-diff]

--mutation loads a CounterfactualMutation from JSON. With no mutation, an empty no-op mutation is used (still produces a cf-derived graph_hash). The cf-run id is minted by GraphRun.counterfactual (cf-<uuid>); the parent's checkpoint rows are byte-identical post-fork (Temporal "cannot change the past" invariant).

Flag	Type	Default	Description
`RUN_ID`	str (arg)	req.	Parent run id to fork the counterfactual from.
`--db PATH`	path	req.	SQLite Checkpointer DB containing the parent run's checkpoints.
`--mutation FILE`	path	(none)	JSON file describing a `CounterfactualMutation` (state overrides, fact asserts, etc.).
`--from-step N`	int (>= 0)	`0`	Step at which to fork the cf-run.
`--diff/--no-diff`	flag	`--no-diff`	After forking, render parent vs cf `RunDiff` as canonical IR JSON.

Examples

# Fork a no-op counterfactual at step 0; print only cf-run-id
stargraph replay 0193... --db .stargraph/run.sqlite

# Fork at step 4 with a state override and print the diff
stargraph replay 0193... --db .stargraph/run.sqlite \
    --mutation cf/override.json --from-step 4 --diff

`stargraph respond`¶

Deliver a HITL response to a run that is awaiting-input. Thin wrapper over POST /v1/runs/{run_id}/respond on a running stargraph serve.

Usage

stargraph respond RUN_ID --response FILE.json --actor NAME [--server URL]

Flag	Type	Default	Description
`RUN_ID`	str (arg)	req.	Run id awaiting input.
`--response FILE`	path	req.	JSON file containing the analyst response payload.
`--actor NAME`	str	req.	Principal id; sent as `Authorization: Bypass <actor>`.
`--server URL`	str	`http://localhost:8000`	Base URL of the running `stargraph serve` process.

The CLI maps HTTP errors to operator-friendly messages:

200 -- RunSummary JSON printed to stdout.
401 -- auth failed for actor=....
404 -- run ... not found or not awaiting input.
409 -- run ... not awaiting input -- already responded or in conflicting state.
Any other non-2xx -- raw response body printed (FR-6).

Example

stargraph respond 0193... --response analyst-decision.json --actor alice

`stargraph simulate`¶

Offline rule-firing trace for an IR. Validates rule logic against caller-supplied synthetic node outputs without invoking any tool, LLM, or checkpoint (FR-9).

Usage

stargraph simulate GRAPH --fixtures FIXTURES

Both arguments are YAML files. FIXTURES is a mapping of node_id to synthetic output dict (one entry per IR node).

Flag	Type	Default	Description
`GRAPH`	path (arg)	req.	Path to an IR YAML graph definition.
`--fixtures FILE`	path	req.	YAML mapping of `node_id` -> synthetic output.

Output format mirrors stargraph run --inspect: a leading graph_hash=<hex> and rule_firings=<count> line followed by one row per rule firing.

Example

stargraph simulate graphs/triage.yaml --fixtures fixtures/triage-zeros.yaml

`stargraph counterfactual`¶

Compute the counterfactual-derived graph_hash for a parent IR + a mutation YAML, without forking a run (FR-27).

Usage

stargraph counterfactual GRAPH --step N --mutate FILE.yaml

Validates the mutation YAML through CounterfactualMutation (extra='forbid', so typos surface here) and prints the cf-derived hash. Use this to verify a mutation file round-trips and to pin the graph_hash you should see in the resulting cf-checkpoint.

Flag	Type	Default	Description
`GRAPH`	path (arg)	req.	Path to the parent run's IR YAML graph definition.
`--step N`	int (>= 0)	req.	Checkpoint step index at which to fork (recorded in output).
`--mutate FILE`	path	req.	YAML file describing a `CounterfactualMutation`.

Example

stargraph counterfactual graphs/triage.yaml --step 4 --mutate cf/swap-tool.yaml

Output:

original_graph_hash=...
cf_step=4
derived_graph_hash=...

`stargraph model rollback`¶

Repoint a model-registry alias (default production) to the version registered immediately before the alias's current target, and append a model_rollback audit event. A pure metadata operation over the existing model_aliases table — no model files are read or verified, so a rollback succeeds even when the current version's file is broken. Refuses (exit 1) when the alias is missing or already points at the earliest registered version.

Usage

stargraph model rollback NAME --registry PATH [--alias NAME] [--audit-log PATH]

Flag	Type	Default	Description
`NAME`	str (arg)	req.	Model id whose alias to roll back.
`--registry PATH`	path	req.	ModelRegistry SQLite DB path.
`--alias NAME`	str	`production`	Alias to repoint.
`--audit-log PATH`	path	`<registry>.audit.jsonl`	JSONL audit log for the rollback event.

`stargraph pack pin` / `stargraph pack revert`¶

Rule packs have no runtime version store: a graph references packs via its IR governance: mounts, whose optional version field is the only durable pin. These commands are metadata edits over that graph YAML — pin sets an explicit version on the mount; revert removes the pin, restoring unpinned (plugin-registry) resolution. Both refuse when the pack id is not mounted; revert also refuses when the mount is not pinned. The mutated document is re-validated as IR before writing, and a pack_pinned / pack_unpinned audit event is appended.

Usage

stargraph pack pin PACK VERSION --graph GRAPH.yaml [--audit-log PATH]
stargraph pack revert PACK --graph GRAPH.yaml [--audit-log PATH]

Flag	Type	Default	Description
`PACK`	str (arg)	req.	Pack id (e.g. `sdw.routing`).
`VERSION`	str (arg)	req. (pin only)	Version to pin the mount to.
`--graph PATH`	path	req.	Graph IR YAML holding the governance mount.
`--audit-log PATH`	path	`<graph>.audit.jsonl`	JSONL audit log for the pin/revert event.

Note: the YAML is rewritten via yaml.safe_dump; the leading comment header is preserved, but inline comments below it are not.

CLI Reference¶

stargraph run¶

stargraph compile¶

stargraph new¶

stargraph serve¶

stargraph inspect¶

stargraph replay¶

stargraph respond¶

stargraph simulate¶

stargraph counterfactual¶

stargraph model rollback¶

stargraph pack pin / stargraph pack revert¶

`stargraph run`¶

`stargraph compile`¶

`stargraph new`¶

`stargraph serve`¶

`stargraph inspect`¶

`stargraph replay`¶

`stargraph respond`¶

`stargraph simulate`¶

`stargraph counterfactual`¶

`stargraph model rollback`¶

`stargraph pack pin` / `stargraph pack revert`¶