# 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 ```text activegraph [] [] ``` 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`](https://docs.activegraph.ai/reference/errors/corrupted-event-payload-error/index.md)). | | 5 | `EXIT_DIVERGENCE` | A strict-mode replay diverged from the recorded log (caught via [`ReplayDivergenceError`](https://docs.activegraph.ai/reference/errors/replay-divergence-error/index.md)). | This table is the single source of truth. The [operating guide](https://docs.activegraph.ai/guides/operating-in-production/index.md) and several error pages reference it. ## Connection URLs Every CLI command that opens a store takes a URL. Two schemes are supported: ```text 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`](https://docs.activegraph.ai/reference/errors/invalid-store-url-error/index.md). 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. ```text activegraph inspect [--run-id ] [--tail N] [--json] [--event ] [--behaviors] [--pack-version] [--memo] [--search ] ``` | Flag | Meaning | | ------------------ | ------------------------------------------------------------------------------- | | `` | Store URL. Required positional. | | `--run-id ` | 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 ` | 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). | | `--memo` | Render memo objects using the same operator format as `activegraph quickstart`. | | `--search ` | Search event ids, types, actors, and payload JSON for a substring. | The selectors (`--event`, `--behaviors`, `--pack-version`, `--memo`, `--search`) 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, one memo list, or one search-results 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. ```text activegraph replay --run-id [--json] ``` | Flag | Meaning | | ---------------- | ------------------------------- | | `` | Store URL. Required positional. | | `--run-id ` | 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`](https://docs.activegraph.ai/reference/errors/replay-divergence-error/index.md). 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`. ```text activegraph fork --run-id --at-event \ [--label ] [--to ] [--set =] [--record] [--json] ``` | Flag | Meaning | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | Source store URL. Required positional. | | `--run-id ` | Parent run to fork from. Required. | | `--at-event ` | Event id at which to fork (inclusive). Required. | | `--label ` | Optional human-readable label for the new run. | | `--to ` | Destination store URL. Defaults to the source store (cross-store fork is not supported in v1.0; use `migrate` first). | | `--set =` | Override a pack setting in the fork. Pack-settings-only; dotted-path `.=`; multiple `--set` flags compose. Syntax and pack-presence errors fail at fork time; unknown setting keys and type errors fail when the pack reloads and validates its settings. | | `--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`](https://docs.activegraph.ai/concepts/forking/index.md). The [fork-and-diff cookbook pattern](https://docs.activegraph.ai/cookbook/common-patterns/index.md) shows the common workflow. **JSON shape**: `{parent_run_id, new_run_id, at_event, label, events_copied, settings_overrides?, settings_override_events?, 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. ```text activegraph diff --run-a --run-b [--json] ``` | Flag | Meaning | | --------------- | ------------------------------- | | `` | Store URL. Required positional. | | `--run-a ` | Left-hand run. Required. | | `--run-b ` | 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. ______________________________________________________________________ ## `promote` Apply a fork's net structural delta to its parent (CONTRACT v1.3 #4; see the [Fork, test, promote](https://docs.activegraph.ai/guides/fork-test-promote/index.md) guide). ```text activegraph promote --run-id --from-run [--dry-run] [--json] ``` | Flag | Meaning | | ------------------ | -------------------------------------------------------------------------------------------------- | | `` | Store URL (SQLite). Required positional. | | `--run-id ` | Destination (parent) run. Required. | | `--from-run ` | Source (fork) run — must be a direct fork of the parent per the store's lineage records. Required. | | `--dry-run` | Compute and print the plan (including conflicts) without applying anything. | | `--json` | Machine-readable output. | Fail-closed and atomic: any conflict between the fork's delta and the parent's own post-fork changes aborts with nothing applied. Warnings (fork-only pack loads, settings overrides) inform but do not block — promote never adopts code. **JSON shape**: `{from_run, into_run, forked_at_event, computed_against, dry_run, objects_created, objects_patched, objects_removed, relations_created, relations_removed, conflicts, warnings}` plus `marker_event_id` and `applied_event_ids` after a real apply. Exits: 0 on success (including a clean dry run), 2 for a bare filesystem path (use a `sqlite:///` URL), 3 when a run doesn't exist or lineage doesn't hold, 5 on conflicts — from an apply refusal or a conflicted `--dry-run` alike, so scripts can gate on the dry run. ______________________________________________________________________ ## `export-trace` Export a run's trace as `text` or `jsonl`. ```text activegraph export-trace --run-id [--format text|jsonl] [--output ] ``` | Flag | Meaning | | ----------------- | --------------------------------------------------------------------------------- | | `` | Store URL. Required positional. | | `--run-id ` | Run to export. Required. | | `--format` | `text` (default; the human-scannable trace) or `jsonl` (one event JSON per line). | | `--output ` | 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. ```text activegraph migrate --from --to \ [--run-id ...] [--skip-corrupted] [--json] ``` | Flag | Meaning | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--from ` | Source store URL. Required. | | `--to ` | Destination store URL. Required. | | `--run-id ` | 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`](https://docs.activegraph.ai/reference/errors/corrupted-event-payload-error/index.md). 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. ```text activegraph pack new [--output-dir ] ``` | Flag | Meaning | | --------------------- | ---------------------------------------------------------------------------------------------------- | | `` | Pack name. Required positional. Becomes the Python module name and the `Pack(name=...)` declaration. | | `--output-dir ` | 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 ` and `pip install -e .`, the pack is discoverable via `activegraph pack list` and loadable via `Runtime.load_pack`. The [Authoring packs](https://docs.activegraph.ai/guides/authoring-packs/index.md) 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. ```text activegraph pack list ``` Prints one pack per line: name, version, distribution name. The underlying mechanism is the same `discover()` API programmatically — see [`load-by-name`](https://docs.activegraph.ai/reference/api/packs/#activegraph.load_by_name) in the API reference. Exits: 0 always (an empty list is not an error). ______________________________________________________________________ ## `quickstart` Run the bundled Diligence demo, or walk through writing a first behavior. ```text activegraph quickstart [--interactive] ``` | Flag | Meaning | | --------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `--interactive` | Start the guided REPL for writing and testing a first behavior. Omit it for the deterministic fixture-backed Diligence demo. | Default mode uses bundled fixtures, no API key, and no network. The output includes the canonical trace, one memo rendered in full, a "what just happened" section, and next-step links. Exits: 0 on success. ______________________________________________________________________ ## What's related - [Operating in production](https://docs.activegraph.ai/guides/operating-in-production/index.md) — the deployed-runtime operator guide. References the EXIT_CODES table here. - [Debugging](https://docs.activegraph.ai/cookbook/debugging/index.md) — the diagnostic walkthrough. Uses every selector flag on `inspect`, plus `fork`, `diff`, and `export-trace`. - [Migration from v0.7](https://docs.activegraph.ai/cookbook/migration-from-v0-7/index.md) — the upgrade runbook. Uses `migrate` and references the URL conventions here. - [`forking`](https://docs.activegraph.ai/concepts/forking/index.md) — the conceptual model for the `fork` command. - [`replay`](https://docs.activegraph.ai/concepts/replay/index.md) — the conceptual model for the `replay` command and the strict-vs-permissive distinction. - [`invalid-store-url-error`](https://docs.activegraph.ai/reference/errors/invalid-store-url-error/index.md) — what fires when a URL is malformed.