Command-line reference¶
The activegraph CLI is a thin wrapper around library APIs
(CONTRACT v0.8 #12). Every operation it performs is also
available programmatically; the CLI is the convenient form for
operators, scripts, and CI.
Invocation¶
Every subcommand supports --help for the autogenerated flag
documentation (activegraph inspect --help). Top-level
activegraph --help lists every subcommand; activegraph
--version prints the installed version.
Exit codes (CONTRACT v0.8 #13)¶
| Code | Constant | Meaning |
|---|---|---|
| 0 | EXIT_OK |
Subcommand succeeded. |
| 1 | EXIT_GENERIC_ERROR |
An unhandled error occurred, or a per-run report contains failures (migrate sets this when any run failed). |
| 2 | EXIT_USAGE_ERROR |
Invalid arguments (click's default — bad flags, missing required options, unparseable values). |
| 3 | EXIT_NOT_FOUND |
A named resource doesn't exist (store, run, event id, behavior name). |
| 4 | EXIT_CORRUPTION |
The store contains data the framework can't decode (caught via CorruptedEventPayloadError). |
| 5 | EXIT_DIVERGENCE |
A strict-mode replay diverged from the recorded log (caught via ReplayDivergenceError). |
This table is the single source of truth. The operating guide and several error pages reference it.
Connection URLs¶
Every CLI command that opens a store takes a URL. Two schemes are supported:
sqlite:///relative/path/to/run.db # three slashes — relative
sqlite:////absolute/path/to/run.db # four slashes — absolute
postgres://user:pass@host:port/dbname # also accepted: postgresql://
Bare filesystem paths are rejected with a clear message
naming the corrected URL — see
invalid-store-url-error.
The framework refuses to silently coerce because guessing wrong
would open an unintended store.
--json convention¶
Every subcommand below supports --json for machine-readable
output. The JSON shapes are documented per-subcommand; the
shapes are stable within a major version (CONTRACT v0.8 #12).
Text output is for human scanning; JSON is for scripts and log
aggregators.
inspect¶
Print a status snapshot of a run.
activegraph inspect <url> [--run-id <run>] [--tail N] [--json]
[--event <evt-id>] [--behaviors] [--pack-version]
| Flag | Meaning |
|---|---|
<url> |
Store URL. Required positional. |
--run-id <run> |
Run to inspect. Defaults to the most recent run in the store. |
--tail N |
Recent events to include. Default 20. |
--json |
Machine-readable output. |
--event <id> |
Print one event's full payload by id. |
--behaviors |
Print only the registered-behaviors section. |
--pack-version |
Print every pack.loaded event (name, version, prompt content hashes). |
The three selectors (--event, --behaviors, --pack-version)
are mutually exclusive — they're focused queries, not filters on
the full status. Combining them is a usage error (exit 2).
JSON shape (default): {run_id, state, queue_depth, events_processed, frame, budget, registered_behaviors, recent_events}. With a selector, the shape narrows to that selector's payload (one event, one behaviors list, one packs list).
Exits: 0 on success, 3 if the store / run / event id doesn't exist, 2 on bad selector combination.
replay¶
Rebuild the graph from a run's event log without firing behaviors.
| Flag | Meaning |
|---|---|
<url> |
Store URL. Required positional. |
--run-id <run> |
Run to replay. Required. |
--json |
Machine-readable output. |
replay runs in permissive mode — it doesn't compare the
re-emitted stream against the recording, so it can't fire
replay-divergence-error.
For strict-mode replay, use the replay_strict=True argument on
Runtime.load programmatically.
JSON shape: {run_id, events, objects, relations}.
Exits: 0 on success, 3 if the store / run doesn't exist.
fork¶
Create a new run by copying events from a parent run up to and
including --at-event.
The --set flag is part of the v1.1 release
--set <pack>.<setting>=<value> is documented in CONTRACT
v1.0 and shown in the signature below, but the implementation
lands in v1.1 (see CONTRACT v1.1 #1).
Until then, use the Python-API form in
Fork with a pack-setting override (v1.0 — Python API)
for fork-with-override workflows. Other flags below (--at-event,
--label, --to, --record, --json) are available now.
activegraph fork <url> --run-id <parent> --at-event <evt> \
[--label <text>] [--to <dest-url>]
[--set <key>=<value>] [--record] [--json]
| Flag | Meaning |
|---|---|
<url> |
Source store URL. Required positional. |
--run-id <parent> |
Parent run to fork from. Required. |
--at-event <evt> |
Event id at which to fork (inclusive). Required. |
--label <text> |
Optional human-readable label for the new run. |
--to <dest-url> |
Destination store URL. Defaults to the source store (cross-store fork is not supported in v1.0; use migrate first). |
--set <key>=<value> |
Override a pack setting in the fork. Pack-settings-only; dotted-path <pack>.<setting>=<value>; multiple --set flags compose; unknown keys fail loud with a registration-time error (see the errors catalog for the family). |
--record |
Mark the fork as a re-recording. The new run accepts new cache entries instead of strict-checking against the parent's prompt hashes. |
--json |
Machine-readable output. |
Fork is the durable parallel-context primitive. The shared-lineage
model and the --set semantics are documented in
concepts/forking. The
fork-and-diff cookbook pattern
shows the common workflow.
JSON shape: {parent_run_id, new_run_id, at_event, label, events_copied, recording?} (recording: true when --record was passed).
Exits: 0 on success, 3 if the parent run or --at-event id doesn't exist, 2 if --to names a different store from the source (cross-store fork not supported).
diff¶
Compare two runs in the same store.
| Flag | Meaning |
|---|---|
<url> |
Store URL. Required positional. |
--run-a <run> |
Left-hand run. Required. |
--run-b <run> |
Right-hand run. Required. |
--json |
Machine-readable output. |
The output is the trio that matters for fork-and-diff workflows: shared events, parent-only events, fork-only events, plus the list of divergent objects and relations (objects that exist in both runs but with different state).
JSON shape: {run_a, run_b, shared_events, parent_only_events, fork_only_events, divergent_objects, divergent_relations}.
Exits: 0 on success, 3 if either run doesn't exist.
export-trace¶
Export a run's trace as text or jsonl.
| Flag | Meaning |
|---|---|
<url> |
Store URL. Required positional. |
--run-id <run> |
Run to export. Required. |
--format |
text (default; the human-scannable trace) or jsonl (one event JSON per line). |
--out <path> |
Destination file. Defaults to stdout. |
jsonl format is the canonical handoff to log aggregators and
event-processing pipelines. Every event lands as one JSON object
per line with the full payload.
Exits: 0 on success, 3 if the store / run doesn't exist.
migrate¶
Copy runs from a source store to a destination store.
activegraph migrate --from <src-url> --to <dst-url> \
[--run-id <run>...] [--skip-corrupted] [--json]
| Flag | Meaning |
|---|---|
--from <src> |
Source store URL. Required. |
--to <dst> |
Destination store URL. Required. |
--run-id <run> |
Migrate only these run(s). Repeat the flag to specify multiple. Defaults to all runs in the source. |
--skip-corrupted |
Skip events whose payload fails JSON decode instead of failing the run. Skipped event ids appear in the per-run report. The destination run is partial — the operator is on notice. |
--json |
Machine-readable output. |
Migration is transaction-per-run, idempotent, one-directional
(CONTRACT v0.8 #5). Each run writes in a single destination
transaction; a failure mid-run rolls back that run's destination
state. Writes use INSERT ... ON CONFLICT DO NOTHING on
(id, run_id) so re-running after a failure is safe.
--skip-corrupted is the recovery primitive for runs containing
CorruptedEventPayloadError.
Without the flag, a corrupted event in any run causes that run
to fail (other runs migrate normally). With the flag, the
corrupted events are recorded in skipped_events on the per-run
report and the rest of the run migrates.
JSON shape: {source_url, dest_url, runs: [{run_id, status, events_migrated, error?, skipped_events?}]}. status is "ok" or "failed".
Exits: 0 if every run's status is "ok"; 1 if any run failed; 2 on a bad source/destination URL.
pack new¶
Scaffold a new pack package skeleton.
| Flag | Meaning |
|---|---|
<name> |
Pack name. Required positional. Becomes the Python module name and the Pack(name=...) declaration. |
--output-dir <path> |
Directory under which to create the package. Defaults to the current directory. |
Generates pyproject.toml, the Python package with stubs for
object types, behaviors, tools, settings, an example prompt, a
smoke test, and a README. After cd <name> and
pip install -e ., the pack is discoverable via
activegraph pack list and loadable via Runtime.load_pack.
The Authoring packs guide is the companion reference.
Exits: 0 on success, 2 on bad arguments.
pack list¶
List installed packs discovered via the activegraph.packs
entry-point group.
Prints one pack per line: name, version, distribution name. The
underlying mechanism is the same discover() API
programmatically — see
load-by-name in the API
reference.
Exits: 0 always (an empty list is not an error).
quickstart¶
Placeholder. The
quickstartsubcommand is documented when the command ships in the v1.0-rc1 work. The shape is locked by the transcript atexamples/quickstart_session.txt— fixture-backed demo of the Diligence pack with a "what just happened" prose section, plus an--interactivemode for writing a first behavior.
What's related¶
- Operating in production — the deployed-runtime operator guide. References the EXIT_CODES table here.
- Debugging — the diagnostic
walkthrough. Uses every selector flag on
inspect, plusfork,diff, andexport-trace. - Migration from v0.7 — the
upgrade runbook. Uses
migrateand references the URL conventions here. forking— the conceptual model for theforkcommand.replay— the conceptual model for thereplaycommand and the strict-vs-permissive distinction.invalid-store-url-error— what fires when a URL is malformed.