CLI reference

Every terminal command the agent-config binary accepts. Run any of them with --help for its flags:

npx -y @event4u/agent-config --help
npx -y @event4u/agent-config init --help

After a global install the binary is on your PATH as agent-config. These are terminal commands; the slash commands your AI tool runs in chat are listed on All slash commands.

The commands you will use

The same groups agent-config --help prints.

Get started

Command	What it does
`init`	Install for your AI tools (opens the setup wizard; –yes stays in the terminal)
`install`	Same setup wizard as init
`doctor`	Check the install and name the next fix
`versions`	List published versions and the one you run

Daily use

Command	What it does
`code-graph`	Ask about the codebase: callers, impact, tests for a change, the project map
`handoff`	Hand the current session over to a fresh one
`council:estimate`	Preview what a second opinion from other models would cost
`council:run`	Get that second opinion (spends only with –confirm)
`ci:settle`	Wait for a pull request’s checks and print the verdict
`gates`	Open decisions that are waiting for you

Inspect

Command	What it does
`explain`	Trace a decision: config \| rule <name> \| route “<text>”
`commands`	List the commands your agent can run
`packs:active`	Which packs are active here, and from which file
`hooks:status`	Which hooks are installed and bound, per tool
`settings:get`	Read one setting and the file its value comes from
`council:status`	Whether a council is configured (no spend)

Configure

Command	What it does
`setup`	Reopen the setup wizard in the browser
`config`	Open the settings page (global; –project for this project)
`settings:set`	Change one setting from the terminal
`use`	Switch the active profile
`keys:install-anthropic`	Store an Anthropic API key for the council
`keys:install-openai`	Store an OpenAI API key for the council

Maintain

Command	What it does
`upgrade`	Install the latest version and refresh your install
`update`	Pin this project to a version
`refresh`	Re-install the current version (–global or –project)
`settings:sync`	Add new setting keys to your settings file (–prune-removed drops retired ones)
`migrate`	Move off an older install layout
`uninstall`	Remove agent-config (–global for the user-scope install)

Every other command

Advanced, maintenance and internal commands, with the synopsis the registry carries. agent-config help --tier=all prints the same set in the terminal; some are hook entry points your AI tool calls, not commands you type.

Command	Synopsis
`adr:effective`	Effective state of one ADR: status, Decision verbatim, clauses its own amendments superseded, active amendments, axes, trigger state. Authorizes nothing.
`affected`	Artefacts related to <artefact> via the discovery relation-graph (BFS).
`analytics`	Local-only workspace analytics: emit\|show\|prune\|migrate (never leaves the machine).
`analyze-session`	Read-only post-session report from on-disk runtime state.
`audit:agents`	What the AI agents, bots and MCP servers in this project can do, against the declared action inventory.
`audit:code`	Security code audit, deterministic half: the two-account route matrix, ledger validation, the derived report, a SARIF import.
`audit:config`	A–F security grade of this project’s assembled agent config (instruction files, MCP, hooks, skills); –min-grade fails a CI step.
`audit:deps`	Security advisories for this project’s packages, runtimes and toolchain; only `refresh` touches the network.
`audit:security`	Security readiness: supply, pipeline, contain and recover lenses — could this project contain a vulnerability disclosed tomorrow.
`benchmark`	Report context-token reduction vs the full always-loaded projection.
`brand:status`	Whether a consumer brand tokens file is present, where, and dot-prefixed near-misses.
`capabilities:index`	Regenerate CAPABILITIES.yaml (the package coverage index); –check for CI.
`chat-history:checkpoint`	Append a phase-boundary entry to agents/runtime/.agent-chat-history.
`chat-history:hook`	Platform hook entry point for chat-history capture (JSON via stdin).
`conformance`	Consumer conformance contract: doctor –ci + installed-and-firing checks.
`conformance:behavior`	Replay local transcripts through the mechanised conformance checks (report, not gate); –why <id> traces one check.
`context-hygiene:hook`	PostToolUse hook entry point — maintains context-hygiene state.
`converge`	Consented cleanup of duplicate install surfaces (surface-matrix driven).
`council:grant-billing`	Record the human yes that lets an exhausted plan quota retry on the metered rung, for ONE run.
`council:quota`	Today’s per-provider CLI-call usage against the enforced cap — zero spend.
`council:render`	Re-render a saved council responses JSON to markdown.
`council:revoke-billing`	End a run-scoped billing grant. Exit 0 when none exists.
`decision:memo`	Record or list an autonomously-resolved question so it stays reviewable (local-only).
`dispatch:hook`	Universal hook dispatcher (runs the resolved concern chain in-process via dist/hooks/dispatch.js).
`doctor-shell`	Native TS-shell environment probe.
`eval:record`	Record a live trigger-eval result into a corpus manifest (corpus-refresh DoD, ADR-061 §6).
`export`	Eject a tool’s canonical content into a chosen path (real file, no symlink).
`first-run`	Guided first-run setup — cost profile, settings, tooling.
`git:convention`	The git convention: show the keys, check subjects, read a ticket, render a branch name, measure the history.
`global`	Install to user-scope paths (~/.claude/, ~/.cursor/, …).
`graph-explain`	Seed on a <concept>, expand 2 hops over the discovery relation-graph with a node budget.
`help`	Show TS-shell help; delegates –tier=N to Bash.
`hooks:doctor`	Diagnose hook health: concerns, posture, missing trampolines (read-only).
`hooks:effect`	Does a bound concern actually FIRE here? Sandboxed synthetic dispatch per concern; five per-concern states, four host verdicts (read-only).
`hooks:install`	Install the combined pre-commit hook.
`hooks:replay`	Replay a fixture through the universal hook dispatcher (no state writes).
`implement-ticket`	Drive the work_engine on a ticket.
`linked-projects:list`	List opted-in IDE-attached sibling repos.
`mcp-server`	Turnkey read-only stdio MCP server over the bundled content (no repo clone; ADR-085).
`mcp:available`	Declared MCP servers, whether each is launchable, and the separate tool registry.
`mcp:check`	Dry-run mcp:render; exit non-zero if targets are stale.
`mcp:render`	Render mcp.json into per-tool MCP client configs.
`mcp:run`	Run the built-in MCP server over stdio (experimental).
`mcp:setup`	Verify the tsx runtime + MCP server module; print the client config snippet.
`media:bundle`	Turn a public post/video URL or a media file into an evidence bundle: frames, contact sheets, transcript rung.
`memory:check`	Validate memory YAML schema + staleness.
`memory:check-proposal`	Run the admission gate on a memory proposal.
`memory:get`	Batch-fetch full memory entries by id (CLI twin of the memory_get MCP tool).
`memory:hash`	Hash a memory entry (YAML or JSON stdin).
`memory:learn`	Aggregate memory intake signals into the local learning sidecar (read-only; –write to emit, –format status for the one-screen view).
`memory:lookup`	Retrieve memory entries (text or JSON envelope).
`memory:signal`	Append a provisional intake signal (memory proposal).
`onboarding-gate:hook`	Hook entry point — writes the onboarding-gate state file.
`packs`	List packs from the discovery manifest (ls subcommand).
`proposal:check`	Validate a learning/skill/rule proposal markdown.
`prune`	Remove project bridge markers not declared in installed-tools.lock.
`reach:doctor`	Reach-channel health report: active backend + pinned fix per channel (read-only; –deep opts into network).
`refine-ticket:detect`	Run the deterministic refine-ticket detection helper.
`roadmap-progress:hook`	PostToolUse hook entry point — regenerates the roadmap dashboard.
`roadmap:archive`	Archive completed roadmaps (PR-gate sweep).
`roadmap:context`	One live situational-awareness probe: open PRs + their file sets, roadmap-tail branches, live sessions, inbox note names, sibling-roadmap keyword hits; –roadmap <slug>, –json.
`roadmap:progress`	Regenerate agents/roadmaps-progress.md from open roadmaps; archives completed ones (–no-archive to skip).
`roadmap:progress-check`	Fail if agents/roadmaps-progress.md is stale (for CI).
`roadmap:set-step`	The single sanctioned writer of a checkbox glyph: advisory lock, line-anchored edit, live step-count invariant, post-write survival check.
`route:audit`	Replay the router matcher over the last N chat-history prompts; opt-in recorder + –weekly rolling render (trigger-match level only).
`route:explain`	Deterministic rule-routing trace for one prompt: matched triggers, tier, disposition, budget, rejected candidates (trigger-match level only). –skills “<task>” ranks SKILLS instead, with each row’s description, on a host with no MCP server.
`routing:doctor`	Live routing diagnosis: per-gate ACTIVE/INACTIVE with reason, chain, freshness, orchestration state (read-only).
`rtk:detect`	rtk (Rust Token Killer) presence + identity readout — contract: docs/contracts/rtk-detection.md.
`run:supervise`	Report runs whose session died with open steps left. Never merges, pushes, or closes.
`self-repair:release`	Publish one defect record as a PR, or an issue when a PR is impossible (Hard-Floor gated).
`self-repair:status`	List queued agent-config defect records (read-only).
`session:recycle`	Validate + write the main-session recycle envelope (–verify validates only, –project names the repo); the successor resumes from it after /clear.
`sessions:claim`	Claim a roadmap for this session so other sessions skip it; –release clears it.
`sessions:list`	List live agent sessions plus unmerged branches held by other worktrees; –json, –branches.
`settings`	Open the local Settings GUI (alias of config).
`settings:check`	Validate .agent-settings.yml against the YAML-subset contract (read-only).
`settings:migrate`	Lift legacy project-local settings into ~/.event4u/agent-config/.
`statusline:install`	Point statusLine at the tap, keeping your status line chained.
`statusline:tap`	Claude Code status-line tap: chains your line, records the plan window for quota notices.
`statusline:uninstall`	Restore the status line the tap replaced.
`stubs:due`	Read-only: roadmap stubs past their review_by: date, plus the decisions routed to the owner. Writes nothing; –json, –counts, –today <ISO>.
`sync`	Replay installed-tools.lock.
`telemetry:record`	Append one artefact-engagement event (default-off).
`telemetry:report`	Aggregate the engagement log into a quartile report.
`telemetry:status`	Print artefact-engagement telemetry status (read-only).
`ui:audit`	Inventory a UI tree into agents/runtime/state/ui-audit.json (Class A; the artefact ui-audit-gate reads).
`ui:render`	Headless capture at desktop / 375px / 320px, or –profile asset for one SVG per class on a light and a dark background, into agents/runtime/state/render/ (Class A; no process survives).
`ui:serve`	Start the local UI server.
`user-data`	Your own data for this repository under your home: list, delete (dry run unless –yes, with tombstones), tombstones, and migrate (dry run first) of chat history and observations.
`validate`	Drift detection on the manifest.
`work`	Drive the work_engine on a prompt.
`workspace:doctor`	Workspace identity with provenance (repo root, main worktree, current worktree, branch, PR base) + session claim and worktree pressure (read-only).
`workspaces`	List workspaces from the discovery manifest (ls subcommand).
`worktree:cleanup`	Worktree inventory and removal of the proven-merged, clean, unused set; never with force.