# CLI and SDK



<a id="section-install"></a>

The package `@c4a/agent-graph` (version 0.3.1, Node.js 20 or later) ships one CLI binary, `agent-graph`, an ESM SDK and the public JSON Schemas and templates. All invocation modes run the same bundled CLI:

```bash
agent-graph ...                    # installed binary
npx @c4a/agent-graph@0.3.1 ...     # npm one-shot
bunx @c4a/agent-graph@0.3.1 ...    # Bun one-shot
node ./agent-graph.mjs ...         # single file shipped beside a Provider bundle
```

| Global option | Meaning |
| --- | --- |
| `-m, --manifest <path>` | Source Provider manifest or built `manifest.json`; default `provider.yaml` |
| `--skill <path>` | Take Provider, Graph and Entry from a Skill's `agent-graph*` metadata; a conflicting explicit Graph or Entry is rejected |
| `--registry <path>` | Host registry for `provider:` Skill locators |
| `--format human\|json` | Concise terminal text (default) or one-line JSON for Agents and automation |
| `-V, --version` | Print the CLI version |



<a id="section-authoring"></a>

## Authoring commands

| Command | What it does |
| --- | --- |
| `init [directory] --id <id>` | Create a minimal Provider: an agent Action, a bound Skill, a procedure, a Code Catalog and a route test. Refuses to replace any path it would generate |
| `import skill <SKILL.md> --into <root> [--graph <id>]` | Copy the whole Skill directory, add a relative binding to the copy, create an agent Action and Graph, append it to the Provider and write `IMPORT_REPORT.md` |
| `import scripts <files...> --into <root> [--graph <id>]` | Create a sequential Graph from scripts; runtime inferred from the extension, effect defaults to `write` |
| `import workflow <yaml-or-json> --into <root> [--graph <id>]` | Convert a compact `steps` / `dependsOn` workflow into edges with default `join: all`; gates, facts and recovery are listed as gaps in `IMPORT_REPORT.md` |

See [Migration](</context/llms/pages/516592ea7ac3e03cb284d8283bf349fc.txt>) for how to finish an imported draft.


<a id="section-discovery"></a>

## Validation and discovery

| Command | What it does |
| --- | --- |
| `validate` | Load the complete reachable Provider and report `valid` or a structured error; no side effects |
| `inspect provider` | List Graphs, entries, node counts, dependencies, Actions, Resources and paths |
| `inspect skill <SKILL.md>` | Show the binding (locator, Provider, `graph#entry`) and resolved Provider; add `--registry` for `provider:` |
| `schema list` / `schema path <name>` / `schema extract <name> --output <path>` | Discover the public JSON Schemas; `extract` works even from a copied single-file CLI |
| `code list` | List the Code Catalog (`route-reason` and `diagnostic` entries) |
| `code locate <code>` | Return the code, summary and optional document location, never the document body |
| `test [file-or-directory]` | Run every YAML/JSON graph test recursively; any failure sets a non-zero exit code |
| `build [output]` | Write a deterministic bundle, default `dist/provider`; output may sit inside the source tree only if it replaces no referenced source |


<a id="section-routing"></a>

## Routing commands

`evaluate [graph]` (omit `graph` with `--skill`) accepts:

| Option | Meaning |
| --- | --- |
| `--entry <name>` | Entry name; default `default` |
| `--state <run.json>` | Take Facts, Outcomes and authorities from a Run |
| `--facts '<json>'` or `--facts @file.json` | Facts, merged over the Run for this invocation |
| `--outcomes '<json>'` or `@file.json` | Outcomes, e.g. `'{"release/inspect":"completed"}'` |
| `--authority <id...>` | Session authorities |

`route <graph> [route-id]`, or `--skill <SKILL.md> route [route-id]`, takes the same options plus:

| Option | Meaning |
| --- | --- |
| `--revision <digest>` | The revision of the preceding Evaluation; a change returns `route-revision-stale` |
| `--resource-receipts '<json>'` or `@file.json` | Current-conversation read receipts that set each resource's `readState` |

Without `route-id`, the current primary Route is resolved. An unavailable ID returns `route-stale`. Route resolution locates files but never runs commands or materializers; a waiting Gate exposes `gate.inspectionAction` and `gate.resolutionAction` separately from its empty `commandPlan`.


<a id="section-run"></a>

## Run commands

```text
run start <graph> --state <path> [--workspace <dir>]
run status --state <path>
run record <node-key> <outcome> --state <path> [--detail <json>]
run facts --state <path> --set <json> [--replace]
run authority --state <path> [--set <id...>]
run checkpoint --state <path> --to <path>
run resume <checkpoint> --state <path>
run events --state <path>
```

`run status` re-evaluates the Graph, so it also needs the Provider options (`--manifest` or `--skill`). `run record` takes the exact key from `route.afterAction.recordNode`, such as `main/work`. `run facts` merges by default and replaces with `--replace`. `run start`, `run checkpoint` and `run resume` refuse to overwrite an existing target (`run-target-exists`). See [Runs and Recovery](</context/llms/pages/708a22de19d0b807fd512451f1269434.txt>).


<a id="section-resource"></a>

## Resource commands

| Command | What it does |
| --- | --- |
| `resource locate <id-or-path>` | Return an installed static file and digest, or a materialization reference for a dynamic resource |
| `resource materialize <id-or-path> --cache <dir> --revision <digest>` | Run a read-only command or script materializer and write content-addressed output plus a receipt |

| `materialize` option | Default |
| --- | --- |
| `--workspace <dir>` | Current directory |
| `--input '<json>'` or `@file.json` | none |
| `--timeout-ms <ms>` | `30000` |
| `--max-output-bytes <bytes>` | `10485760` |
| `--max-error-bytes <bytes>` | `1048576` |

Pass the revision of the Route that selected the view. A host-action Resource is never run by the CLI and returns `materializer-host-required`.


<a id="section-errors"></a>

## Errors

With `--format json`, failures go to stderr with a non-zero exit code:

```json
{
  "schema": "agent-graph.error.v1",
  "state": "error",
  "error": { "code": "route-stale", "message": "...", "diagnostics": [] }
}
```

Branch on `error.code` and diagnostic codes, never on message text.

| Area | Codes |
| --- | --- |
| Routing | `route-revision-stale`, `route-stale`, `route-unavailable` |
| Graph validation | `graph-flow-cycle`, `graph-terminal-missing`, `graph-entry-missing`, `graph-edge-node-missing`, `graph-repeat-target-invalid`, `graph-gated-by-source-invalid`, `graph-recursion`, `terminal-outcome-ambiguous`, `route-reason-code-missing` |
| Gates | `gate-inspection-effect-invalid`, `gate-resolution-effect-invalid`, `gate-delegated-policy-invalid`, `gate-delegated-inspection-missing` |
| Paths and files | `path-outside-provider`, `path-symlink-outside-provider`, `absolute-path-forbidden`, `file-missing` |
| Skill binding | `skill-binding-missing`, `skill-graph-missing`, `skill-entry-missing`, `skill-graph-conflict`, `skill-entry-conflict`, `provider-unresolved` |
| Runs | `run-target-exists`, `run-provider-mismatch` |
| Materialization | `materializer-timeout`, `materializer-output-limit`, `materializer-error-limit`, `materializer-failed`, `materializer-host-required` |
| Host results | `host-action-handler-mismatch`, `host-action-input-stale`, `host-action-output-schema-mismatch` |
| Bundles | `build-output-overlaps-source`, `build-absolute-path-leak`, `bundle-digest-mismatch`, `bundle-file-digest-mismatch`, `bundle-files-mismatch` |
| Tests | `test-path-missing`, `test-cases-empty` |

Evaluation problems are reported as diagnostics inside a successful Evaluation rather than as an error envelope: for example `required-fact-missing` (a reached node is blocked by `requiresFacts`), `no-route` (nothing actionable or terminal is reachable) and the informational `route-alternatives-truncated` when more than three alternatives exist.


<a id="section-sdk"></a>

## SDK

```ts
import { evaluateGraph, loadProvider, resolveRoute, resolveSkillBinding } from "@c4a/agent-graph";
```

| Responsibility | Functions |
| --- | --- |
| Provider discovery | `readSkillBinding`, `resolveSkillBinding`, `readProviderRegistry`, `loadProvider` |
| Routing | `evaluateGraph`, `computeRevision`, `resolveRoute`, `nodeStateKey` |
| Resources and codes | `locateResource`, `materializeResource`, `locateCode`, `hostActionInputDigest`, `validateHostActionResult`, `hostActionOutputDigest`, `hostActionResourceReadReceipt` |
| Optional Run files | `createRun`, `loadRun`, `recordOutcome`, `updateRunFacts`, `updateRunAuthorities`, `checkpointRun`, `resumeRun` |
| Authoring | `initProvider`, `importSkill`, `importScripts`, `importWorkflow` |
| Quality and release | `validateSchema`, `runGraphTests`, `buildProviderBundle`, `inspectProvider` |

Evaluation and route resolution are side-effect free; only the named authoring, Run, build and materialization functions write files. Paths returned by the SDK are resolved for the current installation while definitions stay relative. `materializeResource` accepts `timeoutMs`, `maxOutputBytes` and `maxErrorBytes`, and a trusted host may add variables with `env` (Agent Graph's own variables take precedence). Errors are `AgentGraphError` instances with `code` and `diagnostics`. The package also exports `./schemas/*` and `./templates/*`. A complete host loop is shown in [Skills and Providers](</context/llms/pages/b3558e7c73749da60cf1b9634061fdd8.txt>).

---

## Sources

- [agent-graph/docs/en/cli.md L1–L25 · 9e8b98a](<https://github.com/context4ai/agent-graph/blob/9e8b98a7d4a694a89a1b972e0c9c827c5bd3d772/docs/en/cli.md#L1-L25>)
- [agent-graph/package.json L1–L40 · 9e8b98a](<https://github.com/context4ai/agent-graph/blob/9e8b98a7d4a694a89a1b972e0c9c827c5bd3d772/package.json#L1-L40>)
- [agent-graph/docs/en/cli.md L27–L57 · 9e8b98a](<https://github.com/context4ai/agent-graph/blob/9e8b98a7d4a694a89a1b972e0c9c827c5bd3d772/docs/en/cli.md#L27-L57>)
- [agent-graph/docs/en/cli.md L59–L75 · 9e8b98a](<https://github.com/context4ai/agent-graph/blob/9e8b98a7d4a694a89a1b972e0c9c827c5bd3d772/docs/en/cli.md#L59-L75>)
- [agent-graph/docs/en/cli.md L132–L150 · 9e8b98a](<https://github.com/context4ai/agent-graph/blob/9e8b98a7d4a694a89a1b972e0c9c827c5bd3d772/docs/en/cli.md#L132-L150>)
- [agent-graph/docs/en/cli.md L77–L97 · 9e8b98a](<https://github.com/context4ai/agent-graph/blob/9e8b98a7d4a694a89a1b972e0c9c827c5bd3d772/docs/en/cli.md#L77-L97>)
- [agent-graph/docs/en/cli.md L99–L112 · 9e8b98a](<https://github.com/context4ai/agent-graph/blob/9e8b98a7d4a694a89a1b972e0c9c827c5bd3d772/docs/en/cli.md#L99-L112>)
- [agent-graph/src/runStore.ts L26–L32 · 9e8b98a](<https://github.com/context4ai/agent-graph/blob/9e8b98a7d4a694a89a1b972e0c9c827c5bd3d772/src/runStore.ts#L26-L32>)
- [agent-graph/docs/en/cli.md L114–L130 · 9e8b98a](<https://github.com/context4ai/agent-graph/blob/9e8b98a7d4a694a89a1b972e0c9c827c5bd3d772/docs/en/cli.md#L114-L130>)
- [agent-graph/docs/en/cli.md L152–L168 · 9e8b98a](<https://github.com/context4ai/agent-graph/blob/9e8b98a7d4a694a89a1b972e0c9c827c5bd3d772/docs/en/cli.md#L152-L168>)
- [agent-graph/src/evaluator.ts L200–L210 · 9e8b98a](<https://github.com/context4ai/agent-graph/blob/9e8b98a7d4a694a89a1b972e0c9c827c5bd3d772/src/evaluator.ts#L200-L210>)
- [agent-graph/src/evaluator.ts L316–L324 · 9e8b98a](<https://github.com/context4ai/agent-graph/blob/9e8b98a7d4a694a89a1b972e0c9c827c5bd3d772/src/evaluator.ts#L316-L324>)
- [agent-graph/docs/en/skills-and-providers.md L141–L163 · 9e8b98a](<https://github.com/context4ai/agent-graph/blob/9e8b98a7d4a694a89a1b972e0c9c827c5bd3d772/docs/en/skills-and-providers.md#L141-L163>)
- [agent-graph/src/index.ts L1–L14 · 9e8b98a](<https://github.com/context4ai/agent-graph/blob/9e8b98a7d4a694a89a1b972e0c9c827c5bd3d772/src/index.ts#L1-L14>)
- [agent-graph/src/errors.ts L1–L13 · 9e8b98a](<https://github.com/context4ai/agent-graph/blob/9e8b98a7d4a694a89a1b972e0c9c827c5bd3d772/src/errors.ts#L1-L13>)