CLI reference¶

acx is the zero-dependency reference command-line tool for building, inspecting, verifying, stripping, leveling, and safely sharing .acx Agent Cartridges — and for linting, signing, verifying, inspecting, staffing, and submitting reusable ACX Workflows and Agent Graphs.

Running the tool¶

The reference implementation is pure ESM with no third-party dependencies: it uses only Node's built-in node:sqlite and node:crypto. Because node:sqlite is still gated behind a flag, every invocation must run under node --experimental-sqlite.

node --experimental-sqlite src/cli.mjs <command> …

Running acx with no command (or help, -h, --help) prints usage:

acx — Agent Cartridge (.acx) command-line tool

Usage:
  acx --version
  acx export <agent-package-dir> <out.acx> --publisher <reverse-dns> [--include-field-learned]
  acx inspect <file.acx>
  acx verify  <file.acx> [--registry <trust.json>]
  acx strip   <file.acx> <out.acx>
  acx spec    <file.acx>
  acx check   <file.acx> [--all-tools]
  acx load    <file.acx> [--host claude|codex|cursor]
  acx workflow lint    <workflow.cal.json> [--publish]
  acx workflow sign    <workflow.cal.json> --publisher <reverse-dns> [--key <pem>] [--out <file>]
  acx workflow verify  <workflow.cal.json> [--registry <trust.json>]
  acx workflow inspect <workflow.cal.json>
  acx workflow ready   <workflow.cal.json> [--cartridges <dir>]
  acx graph lint    <graph.agent-graph.json> [--publish]
  acx graph sign    <graph.agent-graph.json> --publisher <reverse-dns> [--key <pem>] [--out <file>]
  acx graph verify  <graph.agent-graph.json> [--registry <trust.json>]
  acx graph inspect <graph.agent-graph.json>
  acx graph digest  <graph.agent-graph.json>
  acx share agent      <file.acx> --slug <slug> [--registry <dir>] [--dry-run]
  acx share workflow   <workflow.cal.json> [--registry <dir>] [--dry-run]
  acx share graph      <graph.agent-graph.json> [--registry <dir>] [--dry-run]
  acx level   <file.acx>

share¶

Prepare a signed agent, workflow, or Agent Graph for the git registry. share performs no git, network, push, or PR operation: it verifies the artifact, enforces safe canonical paths, copies only the public artifact, and generates review metadata.

acx share agent agent.acx --slug research-designer --dry-run
acx share agent agent.acx --slug research-designer

acx share workflow research-council.cal.json --dry-run
acx share workflow research-council.cal.json

acx share graph product-delivery.agent-graph.json --dry-run
acx share graph product-delivery.agent-graph.json

For agents, share requires a valid signed cartridge and clean acx.package-spec/1, then produces registry/cartridges/<publisher>/<id>/<version>/cartridge.acx plus a generated README card. The requested slug must match the ROM-bound artifact id. For workflows, it requires the complete publication profile and valid JCS/DSSE/in-toto publisher binding, then produces registry/cals/<publisher>/<id>/<version>.cal.json. For Agent Graphs, it applies the same signature and publication gates, then produces registry/graphs/<publisher>/<id>/<version>.agent-graph.json. It refuses legacy/unsigned artifacts, tampering, publisher mismatches, unsafe identifiers, secret-like public metadata, and coordinate replacement. Changed bytes require a new SemVer.

Continue with the deterministic index builder and tests:

node --experimental-sqlite tools/build-registry-index.mjs
npm test
git diff --check
git diff -- registry/

See Share ACX for the human path and the bundled $acx-share-agent skill for agent-driven PR preparation.

graph¶

Work with a standalone acx.agent-graph/1 information architecture without assigning or executing tasks. The five public subcommands follow the workflow trust model while keeping organizational communication separate from control flow.

# Validate the public contract.
node --experimental-sqlite src/cli.mjs graph lint \
  product-delivery.agent-graph.json --publish

# Sign. With no --key, a new private key is written beside the output.
node --experimental-sqlite src/cli.mjs graph sign \
  product-delivery.agent-graph.json \
  --publisher io.github.yourhandle \
  --out product-delivery.signed.agent-graph.json

# Verify and inspect without executing anything.
node --experimental-sqlite src/cli.mjs graph verify \
  product-delivery.signed.agent-graph.json
node --experimental-sqlite src/cli.mjs graph inspect \
  product-delivery.signed.agent-graph.json
node --experimental-sqlite src/cli.mjs graph digest \
  product-delivery.signed.agent-graph.json

lint accepts fuzzy prose and selectors but fails closed on hard invariants. Routes cannot point back to their own source. Required direction cannot have conflicting owners or cycles. Expected returns must name a real reverse route. Loop participant bindings cannot be ambiguous. Every convergence has at least two distinct loop inputs and positive wait/round limits; graph-wide propagation and fan-out are bounded.

Publishable graphs add a stricter safety profile: discovery metadata must not look like credentials or private key material, and every referenced ACX Workflow is pinned by publisher id, workflow id, SemVer, and canonical digest. Knowledge modules contain descriptions, stewards, audiences, and optional metadata locators — never the knowledge payload itself.

graph digest removes only top-level integrity, canonicalizes with RFC 8785/JCS, and prints the sha256 digest used by registry identity, workflow dependency pins, and signed remix lineage.

See the visual Agent Graph guide for the Product Owner ↔ Developer reporting loop and the research + delivery convergence pattern.

workflow¶

Work with a standalone acx.cal/1 team workflow without executing it. The five subcommands deliberately separate a portable artifact's validity and trust from one machine's ability to staff it.

acx cal <file> [--cartridges <dir>] remains a backward-compatible alias for workflow ready.

Share a workflow¶

# 1. Portable validation: no local cartridges required.
node --experimental-sqlite src/cli.mjs workflow lint team.cal.json --publish

# 2. Sign. With no --key, a new private key is written beside the output.
node --experimental-sqlite src/cli.mjs workflow sign team.cal.json \
  --publisher io.github.yourhandle --out team.signed.cal.json

# 3. Anyone can verify the exact shared graph before staffing or execution.
node --experimental-sqlite src/cli.mjs workflow verify team.signed.cal.json

# 4. The receiving studio checks whether its local roster can fill every slot.
node --experimental-sqlite src/cli.mjs workflow ready team.signed.cal.json \
  --cartridges ./roster

Signing covers every top-level field except integrity using RFC 8785/JCS and binds the digest into an in-toto Statement carried by DSSE. The generated private key stays outside the JSON and must never enter git. A valid but unregistered signer is portable; a namespace-proven trust-registry entry upgrades it to trusted; content or identity tampering is tampered.

export¶

Package an AGENTIBUS agent-package directory into a signed .acx cartridge.

Synopsis

node --experimental-sqlite src/cli.mjs export \
  <agent-package-dir> <out.acx> \
  --publisher <reverse-dns> [--include-field-learned]

Options

What it does

1. Generates a fresh ed25519 signing key and derives keyid = "ed25519:" + hex(sha256(DER SPKI)).
2. Builds the ROM (skills, capabilities, meta), then signs a content-addressed ROM manifest recomputed from live bytes in a DSSE / in-toto envelope. See Signing & trust.
3. Writes the cartridge, then writes the private key to <out.acx>.key.pem (mode 0600) OUTSIDE the cartridge.

By default, field-learned memory is quarantined — the fail-closed scrub gate (SPEC §7.5) and the two-tier partition keep codebase-specific records out of what you ship unless you opt in with --include-field-learned. See Memory.

node --experimental-sqlite src/cli.mjs export \
  ./agent-package /tmp/demo.acx \
  --publisher io.github.agentibus

cartridge id:   io.github.agentibus/scenario-research-designer@025edd67-cc60-47b8-a059-ddd839c29db5
rom hash:       sha256:f479be021b8ea2e55cc6e3e33b95df9d151196548dfc854dedbe578be7120642
keyid:          ed25519:17bb8c9290fd2a3d0c3a434ad0e99544d809dbff1540d64be0bab2274df14f66
signing key:    /tmp/demo.acx.key.pem  (private — keep secret, outside cartridge)
field-learned:  quarantined (default)
wrote:          /tmp/demo.acx

The rom hash printed here (sha256:f479be02…7120642) is the value that every later command binds to.

inspect¶

Print meta, ROM object counts, skills, capabilities, memory zone counts, and attestations for a cartridge. Read-only.

Synopsis

node --experimental-sqlite src/cli.mjs inspect <file.acx>

Options — a single positional <file.acx>; no flags.

What it does — opens the cartridge read-only and prints six sections: meta (all acx.* keys, sorted), the ROM object total grouped by kind, the acx_skill rows, the capabilities rows (with each capability's verified flag), memory counts grouped by zone, and any attestations.

node --experimental-sqlite src/cli.mjs inspect /tmp/demo.acx

== meta ==
  acx.agent_name = Scenario Research Designer
  acx.cartridge_id = io.github.agentibus/scenario-research-designer@025edd67-cc60-47b8-a059-ddd839c29db5
  acx.created_at = 2026-04-03T13:35:46.190Z
  acx.declared_level = 4
  acx.embedding_engine = {"id":"local-hash-128","dim":128}
  acx.model = gemini-2.5-pro
  acx.provider = gemini
  acx.publisher_id = io.github.agentibus
  acx.role = designer
  acx.rom_manifest_hash = sha256:f479be021b8ea2e55cc6e3e33b95df9d151196548dfc854dedbe578be7120642
  acx.spec_version = 0.1
  acx.vec0_format = 1

== ROM objects ==
  total: 21  (memory:1, cartridge:9, sqlar:11)

== skills (acx_skill) ==
  - expertise-designer: Specialized designer expertise on research, ux, benchmarking. Use when a task matches this agent's d

== capabilities ==
  - implement-feature[pkg:generic/benchmarking+pkg:generic/research+pkg:generic/ux]  verified=false
  - build-dag[pkg:generic/snowflake+pkg:pypi/apache-airflow+pkg:pypi/dbt-core]  verified=false

== memory (by zone) ==
  rom: 1

== attestations ==
  (none)

verify¶

Evaluate the SPEC §4.5 trust taxonomy for a cartridge. Exits non-zero when the result is invalid or tampered.

Synopsis

node --experimental-sqlite src/cli.mjs verify <file.acx> [--registry <trust.json>]

Options

What it does — recomputes the ROM manifest from live bytes, checks the DSSE signature, and maps the outcome onto the trust taxonomy:

With no --registry, an empty registry is used, so a validly-signed cartridge from an unknown signer resolves to portable with status: warning (a caution, not a failure — exit=0).

node --experimental-sqlite src/cli.mjs verify /tmp/demo.acx

status:   warning
trust:    portable
summary:  Signature valid but signer not in trust registry.
keyid:    ed25519:17bb8c9290fd2a3d0c3a434ad0e99544d809dbff1540d64be0bab2274df14f66
signedAt: 2026-04-03T13:35:46.190Z
issues:   Signer keyid not in trust registry
exit=0

strip¶

Copy a cartridge, remove the SAVE zone, and print the ROM hash-equality proof. Exits non-zero if the hashes differ.

Synopsis

node --experimental-sqlite src/cli.mjs strip <file.acx> <out.acx>

Options — two positionals: the source <file.acx> and the SAVE-free destination <out.acx>; no flags.

What it does — copies the file, drops every SAVE-zone row, and re-derives the ROM manifest hash from the stripped result. Because the ROM was never mutated, the hash before and after stripping are byte-for-byte equal — a cryptographic demonstration that the mutable, field-learned SAVE memory was purely additive and the signed, immutable ROM core stands alone (SPEC §3.4).

node --experimental-sqlite src/cli.mjs strip /tmp/demo.acx /tmp/demo.rom.acx

rom hash before strip: sha256:f479be021b8ea2e55cc6e3e33b95df9d151196548dfc854dedbe578be7120642
rom hash after  strip: sha256:f479be021b8ea2e55cc6e3e33b95df9d151196548dfc854dedbe578be7120642
hash-equality proof:   EQUAL (ROM intact; SAVE removed)
wrote:                 /tmp/demo.rom.acx
exit=0

level¶

Run the demo benchmark with an independent verifier key, issue a level credential if the gate passes, and write the VC next to the cartridge.

Synopsis

node --experimental-sqlite src/cli.mjs level <file.acx>

Options — a single positional <file.acx>; no flags.

What it does

1. Reads the cartridge's ROM digest and constructs a subject id urn:acx:cartridge:<cartridge_id>.
2. Generates a separate verifier key/identity (did:web:verifier.acx.dev) — never the publisher's key — and re-runs the pinned ROM against a benchmark with a sealed held-out slice.
3. Applies the TrueSkill σ-gate (sigma < 1.5, gamesPlayed ≥ 30, conservative R = mu − 3·sigma). Only on pass does it issue a W3C VC 2.0 + Open Badges 3.0 credential bound to the ROM digest.
4. Attaches the attestation to the cartridge (so inspect surfaces it) without mutating the signed ROM capability — the ROM signature is left intact — and writes the VC to <file>.level-attestation.json.

The reference competence=33 agent clears the gate and earns acxLevel 29, tier principal.

node --experimental-sqlite src/cli.mjs level /tmp/demo.acx

cartridge rom digest: sha256:f479be021b8ea2e55cc6e3e33b95df9d151196548dfc854dedbe578be7120642
benchmark: acx-bench-dag-de@2026.07.1 (160 tasks, held-out 96)

level: ISSUED
  acxLevel:  29
  tier:      principal
  rating:    mu=32.85 sigma=1.191 games=90 pass@1=60% R=29.27
  credential verify: VALID
  capability build-dag -> resolvable as VERIFIED via attestation (ROM signature left intact)
wrote VC: /tmp/demo.level-attestation.json
exit=0

End-to-end¶

A cartridge is a self-contained, signed harness — the agent-OS image — that any host boots via the harness-requirements handshake. The CLI walks the full lifecycle:

flowchart LR
  A["agent-package dir"] -->|export| B[".acx (signed ROM)"]
  B -->|inspect| C["meta / skills / caps"]
  B -->|verify| D["trust taxonomy"]
  B -->|strip| E["ROM-only .acx<br/>hash EQUAL"]
  B -->|level| F["σ-gated VC<br/>bound to ROM digest"]

See also: Proofs (reproducible scripts and assertions) · Conformance · Schemas · Signing & trust · Distribution.