AgentBoot CLI Reference

Reference for all implemented CLI commands. Run agentboot --help for a summary or agentboot <command> --help for command-specific help.

Global Options

Flag	Description
`-c, --config <path>`	Path to `agentboot.config.json`
`--verbose`	Show detailed output
`--quiet`	Suppress non-error output
`--debug`	Show debug output (LLM responses, raw data)
`-v, --version`	Print version

`agentboot build`

Compile traits into persona output files. Reads agentboot.config.json, resolves trait references, and emits self-contained output under dist/.

agentboot build
agentboot build -c path/to/config.json

`agentboot validate`

Run pre-build validation checks (8 checks):

Persona existence — all enabled personas found in core/personas/
Trait references — all traits in persona configs exist in core/traits/
SKILL.md frontmatter — required fields present
Secret scanning — no credentials in definitions
Composition consistency — no scope conflicts between rule/preference types
Rule override detection — lower scopes shadowing rule-type core artifacts
MCP governance — approved/required server validation against mcp config
HARD guardrails — lower scopes cannot override HARD-classified artifacts

agentboot validate
agentboot validate --strict

Flag	Description
`-s, --strict`	Treat warnings as errors

Exit codes: 0 = pass, 1 = errors, 2 = warnings (with --strict).

Validation also checks the hub's agentboot-exceptions.json (the policy-exception file): malformed or field-incomplete exceptions fail, expired exceptions are treated as absent (the underlying failure resurfaces), and exceptions expiring within 14 days produce warnings. See configuration § Policy exceptions.

`agentboot test`

Snapshot and regression testing over the compiled dist/ tree. Deterministic: no LLM call, no cost, no login, safe to run in CI.

agentboot test --snapshot                 # Create/update snapshot baseline from dist/
agentboot test --regression               # Compare dist/ against saved snapshot
agentboot test --regression --snapshot-file .agentboot-snapshot.json

Flag	Description
`--snapshot`	Create or update snapshot baseline from current `dist/`
`--regression`	Compare current `dist/` against saved snapshot
`--snapshot-file <path>`	Path to snapshot baseline file (default: `.agentboot-snapshot.json`)

Both compare SHA-256 hashes of the files under dist/: --snapshot writes the baseline, --regression diffs against it and reports added, removed and changed files. Exit non-zero on a difference, so a prompt change that alters compiled output cannot land unnoticed.

Behavioral evaluation is NOT part of the v1.0 surface. There is no supported command or flag for "given this input, does the persona actually behave this way" — v1.0 ships the deterministic half only. Ruled 2026-08-11: the scenario runner parses and executes cases, but the large majority of the expectations in the shipped scenario set are judgement calls with no mechanical evaluator, so a green run would not have meant what a reader would reasonably take it to mean, and shipping the flag at 1.0 would have frozen that reading into the tag. Tracked as behavioral evaluation on the roadmap. For static persona checks that DO ship, use agentboot lint and agentboot validate.

`agentboot migrate`

Convert an existing repo with agentic content into an AgentBoot hub. Scans for .claude/, .cursorrules, copilot-instructions.md, classifies content, scaffolds the hub structure, and imports whole-file content deterministically.

agentboot migrate                         # Migrate current directory
agentboot migrate --path /path/to/repo    # Migrate specific repo
agentboot migrate --dry-run               # Preview changes
agentboot migrate --revert                # Undo migration from backup
agentboot migrate --org my-org            # Specify org slug

Flag	Description
`--path <dir>`	Repo directory to migrate (default: cwd)
`--revert`	Undo a previous migration using saved backup
`--dry-run`	Preview what would change without modifying files
`--org <name>`	Org slug for the new hub (default: directory name)

LLM classification is NOT run during migration. Run agentboot import after migration for files needing LLM classification.

`agentboot sync`

Distribute compiled output from dist/ to target repositories listed in repos.json.

agentboot sync
agentboot sync --repos-file path/to/repos.json
agentboot sync --dry-run

Flag	Description
`--repos-file <path>`	Path to repos.json (default: `./repos.json`)
`-d, --dry-run`	Preview changes without writing
`--force`	Override drift detection (overwrite modified files)
`--adopt-existing`	Allow a FIRST sync to replace pre-existing bespoke instruction files (they are archived first; consider `import` instead)

First sync onto a repo with existing agent config

A first sync against a repo that already has hand-written instruction files (CLAUDE.md, AGENTS.md, .cursorrules, .github/copilot-instructions.md) stops with an error instead of replacing them. That replacement has to be a deliberate choice:

Import first (recommended): agentboot import --path <repo> decomposes the bespoke content into hub artifacts, so nothing is lost by construction — then sync.
Replace anyway: agentboot sync --adopt-existing. Before writing anything, sync archives the pre-existing content it will overwrite — the target directory's contents and all root-level artifacts sync manages (CLAUDE.md, .mcp.json, AGENTS.md, .cursorrules, .github/copilot-instructions.md) — to the target directory's .agentboot-archive/ (.claude/.agentboot-archive/ by default), alongside an archive-manifest.json recording what was archived and when. The originals stay recoverable; agentboot uninstall restores them automatically.

The archive is created only on the first sync to a repo; subsequent syncs are governed by drift detection against .agentboot-manifest.json.

Provenance, risk summaries, and manifest integrity

Every sync writes a .agentboot-manifest.json that is both the drift baseline and a provenance/integrity record:

Provenance — the hub commit (with a dirty-tree flag), AgentBoot version, and sha256 hashes of agentboot.config.json and agentboot-exceptions.json, so a spoke can always answer which hub state produced these artifacts.
Integrity — a sha256 content digest over the whole manifest, plus an SSH signature when the hub sets sync.signing (see configuration). Verify either with agentboot verify-manifest.
The manifest inventories all managed files delivered to the repo, including files skipped as already-identical on re-sync.

In PR mode (sync.pr.enabled), the PR body carries the provenance block and a risk-classified change summary: enforcement-affecting files (hooks, managed settings, MCP config, delivered executables) are listed individually for careful review; config wiring and advisory content are summarized by count. Generated config should be reviewed like any change to CI or repo settings.

`agentboot verify-manifest`

Verify a synced .agentboot-manifest.json: the manifest content digest, every listed file's hash, and the SSH signature when present. Exits non-zero on any mismatch — suitable as a CI step in spoke repos.

agentboot verify-manifest
agentboot verify-manifest --repo ~/work/my-service
agentboot verify-manifest --manifest .claude/.agentboot-manifest.json

Flag	Description
`--repo <path>`	Repo to verify (default: cwd)
`--manifest <path>`	Explicit manifest path

Signature verification checks cryptographic validity for the recorded digest (ssh-keygen -Y check-novalidate). Pinning WHO may sign is the org's CI concern — keep an allowed_signers file and check the manifest's integrity.signature.signer_public_key against it.

`agentboot mcp-pin`

Record a sha256 digest over each approved MCP server's live tool definitions — the pin that agentboot mcp-verify re-checks for rug-pulls (a server changing its tool descriptions under an unchanged name). Per-tool hashes are written to a sidecar (agentboot.mcp-pins.json) so a later mismatch can name the exact tools that changed.

agentboot mcp-pin
agentboot mcp-pin --server my-server --write

Flag	Description
`--server <name>`	Pin a single approved server (default: every approved server with a `command` or `url`)
`--write`	Update `agentboot.config.json` in place (`toolsDigest` + `toolsDigestRecordedAt`; per-tool hashes go to `agentboot.mcp-pins.json`)

Without --write, the command prints the digest it would record. Note: --write re-serializes the config with JSON.stringify(…, 2) — JSONC comments are not preserved. Exit code 1 if any server could not be pinned.

`agentboot mcp-verify`

Re-hash each approved MCP server's live tool definitions (stdio and https transports) against its recorded toolsDigest — the use-time rug-pull check. Run it in CI or before rollout. On mismatch it names the added/removed/changed tools when a per-tool baseline exists in the pin sidecar.

agentboot mcp-verify
agentboot mcp-verify --strict
agentboot mcp-verify --pins .claude/mcp-pins.json    # spoke side, no hub needed

Flag	Description
`--server <name>`	Verify a single approved server
`--strict`	Unpinned approved servers FAIL instead of warn
`--pins <path>`	Spoke side: verify against a synced `mcp-pins.json` (e.g. `.claude/mcp-pins.json`) instead of a hub config

The --pins CI/spoke path is fail-closed: an approved server with no toolsDigest fails (a missing pin means the rug-pull check is a no-op for that server, which must not read as "verified"). Hub-side runs are warn-only on unpinned servers unless --strict. Exit code 1 on any mismatch, connection error, or (under --strict/--pins) unpinned server; an all-pinned-and-matching run is the only result reported as verified.

`agentboot dev-build`

Run the full local development pipeline: clean, validate, build, dev-sync.

agentboot dev-build

This is equivalent to running clean -> validate -> build -> dev-sync in sequence. Exits on the first failure.

`agentboot install`

Interactive onboarding wizard. Establishes the personas repo (the org's prompt source code) or connects a code repo to an existing one.

agentboot install
agentboot install --hub --org acme
agentboot install --connect --hub-path ~/work/personas

Flag	Description
`--hub`	Create a new personas repo (architect path)
`--connect`	Connect this repo to an existing personas hub (developer path)
`--org <name>`	Organization name (auto-detected from git remote if omitted)
`--path <dir>`	Where to create the personas repo (default: recommended based on cwd)
`--hub-path <dir>`	Path to existing personas repo (for `--connect`)
`--non-interactive`	Skip all interactive prompts; use env var defaults (see below)
`--skip-sync`	Skip the optional sync step after connecting

Two paths:

Path 1 (architect): Creates a new personas repo with config, traits, personas, and instructions. Auto-runs agentboot build. Optionally registers and syncs the first target repo.
Path 2 (developer): Finds the org's personas repo (scans siblings, checks GitHub org via gh), creates a branch with the repos.json change, and offers to open a PR.

Content detection: During install, the wizard scans nearby directories for existing agentic content — .claude/ directories, root CLAUDE.md, .cursorrules, .github/copilot-instructions.md, and .github/prompts/*.prompt.md files. For each directory with content, the wizard offers to note it for import and prints the agentboot import --path <dir> command to run after install. Import is not executed during install (it requires LLM access). You can also check additional directories interactively.

Same-org repo registration (Path 1): After registering the first target repo, the wizard extracts the git org from that repo and scans sibling directories for other repos with matching org. Each match is offered for individual registration. You can also register additional repos by path interactively.

If agentboot.config.json already exists in cwd, exits with a message to use doctor.

setup is a hidden alias for install (deprecated).

Non-interactive mode environment variables:

Variable	Default	Description
`AGENTBOOT_ORG`	`my-org`	Organization slug
`AGENTBOOT_ORG_DISPLAY`	`My Organization`	Organization display name
`AGENTBOOT_HOOKS`	`false`	Set to `true` to enable hooks
`AGENTBOOT_SYNC`	`false`	Set to `true` to enable sync
`AGENTBOOT_PERSONAS`	all defaults	Comma-separated persona names

Example CI usage:

AGENTBOOT_ORG=acme npx agentboot install --non-interactive

`agentboot install-user`

Install compiled skills/rules to your user scope (~/.claude), or stage them for an external manager. Controlled by userLevel.mode in agentboot.config.json (see Configuration).

agentboot install-user
agentboot install-user --dry-run
agentboot install-user --mode manifest
AGENTBOOT_USER_LEVEL_MODE=manifest agentboot install-user

Flag	Description
`--dry-run`	Show what would be written/staged without changing anything
`--mode <mode>`	Override the write mode: `auto` (default), `direct`, or `manifest`

Env var	Description
`AGENTBOOT_USER_LEVEL_MODE`	Same three values. For callers that can set an environment variable but cannot edit the hub config or reach the flag (CI jobs, wrapped installers). Lower precedence than `userLevel.mode` and `--mode` — including an explicitly passed `--mode auto`, which suppresses it.

auto writes ~/.claude directly unless a ~/.claude/.managed sentinel indicates another tool owns the slot (then it stages a handoff manifest); manifest never writes and only stages the resolved content plus a manifest for an external provider to apply.

direct writes ~/.claude — except when the sentinel is present, where it is refused rather than honoured. The sentinel is the only signal from the side of the boundary AgentBoot cannot see, so no config key or flag may override it. On refusal: ~/.claude is untouched, the content is staged for handoff anyway, the refusal is printed naming the source that asked for direct, and the command exits 1. A silent downgrade to manifest mode under a green success line would be the same green-over-a-refusal failure the exit code exists to prevent. To resolve it, remove ~/.claude/.managed if AgentBoot owns the slot, or stop requesting direct.

A mode value that is not auto/direct/manifest, from either the config or the env var, is likewise refused — it stages, reports, and exits 1 rather than falling back to auto.

`agentboot import`

Scan and classify existing AI agent content (.claude/, CLAUDE.md, .cursorrules, Copilot instructions) into personas, traits, gotchas, and instructions in the personas repo. Never modifies or deletes original files.

agentboot import
agentboot import --path ~/work/
agentboot import --overlap
agentboot import --apply

Flag	Description
`--path <dir>`	Directory or repo to scan (default: cwd)
`--url <github-url>`	Import from a GitHub URL (repo or raw file)
`--parent <dir>`	Scan all subdirs of a parent directory (expanded import pipeline)
`--hub-path <dir>`	Path to personas repo (auto-detected from siblings if omitted)
`--overlap`	Run heuristic overlap analysis against hub and cross-import content
`--apply`	Apply a previously generated import plan (`.agentboot-import-plan.json`)
`--retry-failed`	Retry files that previously timed out (`.agentboot-import-failed.json`)
`--non-interactive`	Auto-apply items the classifier marks high confidence (categorical); medium/low are left for review
`--isolated`	Test prompts without user Claude settings (uses temp config)

This is an LLM-powered command — it uses claude -p to classify content. Requires an active Claude Code login. See concepts for the command classification model.

Org-scale sweeps and cross-repo dedup

import --parent scans every repo under a directory in one sweep. When the same content lives in multiple repos — the classic "identical boilerplate in 16 repos" problem — the sweep converges it onto one promoted org artifact instead of importing N copies:

The first repo's copy is planned as create; later copies of the same artifact are planned as merge. The plan and apply output list each promotion as <artifact> ← repoA, repoB.
Duplicate content is never re-appended and never overwritten. A later copy whose content matches records its repo in the artifact's frontmatter (additional_sources:) and counts as Skipped; a later copy with distinct content under the same name is appended and counts as Updated.
A copy matching an artifact already in the hub (from an earlier sweep) is skipped, but its repo is still recorded as a source — re-running the sweep across the fleet accretes provenance instead of losing it.
Repo-specific content ("residuals") imports normally, attributed to its repo.

Every imported artifact carries source: (first contributing repo) and, when promoted, additional_sources: in its frontmatter — so "which repos rely on this rule" stays answerable from the artifact itself.

Promotions are recorded in the staged import plan (.agentboot-import-plan.json) under the cross_repo_promotions field: an array of { "target_path": "<hub artifact path>", "repos": ["repoA", "repoB"] } entries, one per hub artifact fed by two or more distinct repos in the sweep. The field is absent on plans staged before v0.13.0; import --apply recomputes promotions from the plan's whole-file imports in that case.

`agentboot add <type> <name>`

Scaffold a new component. The name argument must be 1-64 lowercase alphanumeric characters with hyphens (e.g., my-new-persona). For the prompt type, name is the content or file path to classify; for the template type, name is the template name.

agentboot add persona my-reviewer
agentboot add trait my-trait
agentboot add gotcha database-rls
agentboot add domain healthcare
agentboot add hook compliance-gate
agentboot add prompt ./path/to/file.md
agentboot add template sdlc-orchestrator

Supported types

Type	Creates
`persona`	`core/personas/<name>/SKILL.md` + `persona.config.json`
`trait`	`core/traits/<name>.md`
`gotcha`	`core/gotchas/<name>.md` (with `paths:` frontmatter)
`domain`	`domains/<name>/` directory with manifest, README, and subdirectories
`hook`	`hooks/<name>.sh` (executable shell script with hook template)
`prompt`	Classify a raw prompt or file using `import` (LLM-powered)
`template`	Install a pre-packaged harness bundle from a shipped template (e.g. `sdlc-orchestrator`); applies all-or-nothing

`agentboot doctor`

Check environment and diagnose configuration issues. Validates Node.js version, git, Claude Code availability, config parsing, persona/trait existence, repos.json, and dist/ status.

agentboot doctor
agentboot doctor --fix
agentboot doctor --fix --dry-run
agentboot doctor --format json

Flag	Description
`--fix`	Attempt to auto-fix issues (e.g., rebuild stale dist/, set missing config fields)
`--dry-run`	Preview what `--fix` would do without making changes
`--format <fmt>`	Output format: `text` (default), `json`

When --fix is used, doctor reports issuesFound, issuesFixed, and issuesRemaining counts. Issues that cannot be auto-fixed (e.g., missing Node.js) are reported with manual remediation steps.

Exit code 1 if any issues remain after fixing.

`agentboot drift-check`

Check spoke repos for drift against their sync manifest — reports files that were modified or removed since the last sync (drift is detected, not prevented).

agentboot drift-check
agentboot drift-check --repo ~/work/my-service
agentboot drift-check --format json

Flag	Description
`--repo <path>`	Check a specific repo (defaults to all repos in `repos.json`)
`--format <type>`	Output format: `text` (default) or `json`

Approved drift is expressed through the policy-exception workflow: a spoke's .agentboot-exceptions.json with an unexpired "policy": "drift:<path-or-glob>" entry makes the covered file report as excepted (with its exception id) instead of failing. Expired exceptions are ignored and the drift resurfaces, naming the owner. See configuration § Policy exceptions.

`agentboot conformance`

Empirically test compiled enforcement per platform and write a machine-readable enforcement manifest into the artifacts. The harness EXECUTES the compiled hook scripts with crafted inputs — clean, secret-bearing (canary), malformed, oversized, deny-listed tool — and compares observed exit codes and blocking decisions against the declared enforcement level.

agentboot conformance
agentboot conformance --platform claude
agentboot conformance --format json

Flag	Description
`--platform <name>`	Test a single platform (default: all configured output formats)
`--format <type>`	`text` (default) or `json`

Results land in dist/<platform>/enforcement-manifest.json: the platform's declared level (the same single source of truth doctor reports), each control's mechanism, and per-probe expected vs observed outcomes.

Honesty rules: a control that cannot be probed (no bash, script missing) is reported untested, never assumed to pass; advisory platforms (Cursor, Windsurf, Gemini, JetBrains, AGENTS.md, skills) get a manifest stating plainly that no enforcement mechanism exists. Exit code is non-zero when any probe's observed behavior diverges from the declaration — suitable as a CI gate (it runs in AgentBoot's own CI on every build). See platform-capability-matrix for the classification this harness tests.

`agentboot baseline`

Archive a dated conformance snapshot. Platforms change their enforcement semantics without announcing it, and when they do your corpus text does not move — so drift-check keeps reporting clean while the governance quietly stops working. Detecting that needs a record of how the platforms behaved before, and a baseline cannot be backfilled: probes that start next year cannot say how a platform behaved at your 1.0.

agentboot baseline
agentboot baseline --dir .agentboot/baseline

Flag	Description
`--config <path>`	Path to `agentboot.config.json` (the hub is its directory)
`--dir <path>`	Archive directory (default: `.agentboot/baseline`)

Reads the enforcement manifests agentboot conformance writes into dist/<platform>/ and stores a timestamped conformance-<stamp>.json snapshot: the AgentBoot version, the capture time, and each platform's per-probe results.

This command is the archive only. It performs no comparison and produces no report — reading these snapshots against each other is post-GA work. The point is to start a clock that cannot be restarted, so run it on a schedule from now on.

Two states are refusals rather than empty snapshots, because a baseline that silently accumulates nothing looks healthy for a year:

No enforcement manifests in dist/ — exits non-zero and points at agentboot conformance. Nothing is archived.
Manifests present but zero probes observed (every control untested or not-applicable) — exits non-zero. A file count is not a measurement, and banking an unmeasured snapshot as history is worse than banking none, because later it reads as history.

`agentboot identity`

Stamp permanent identifiers onto governed artifacts: mints an id for any artifact that lacks one and refreshes the content hash on any whose body has changed. Covers core/instructions/, core/traits/ and core/gotchas/.

agentboot identity --dry-run
agentboot identity

Flag	Description
`--config <path>`	Path to `agentboot.config.json` (the hub is its directory)
`--dry-run`	Report what would change without writing

Identity is what lets an artifact be traced across renames, scope moves and spoke syncs. It cannot be applied retroactively — an artifact left unstamped can only ever date from whenever it is finally stamped — which is why the backfill exists as its own command rather than as a build step.

Traits and gotchas carry no frontmatter by convention; identity creates a minimal block for them. Navigational files (README.md, index.md) are never stamped: a README is not a governed artifact. A duplicate id across two files is a hard error — it would silently merge two artifacts' histories forever.

`agentboot status`

Show deployment status: org info, enabled personas, traits, output formats, registered repos with sync state, and last build time.

agentboot status
agentboot status --format json

Flag	Description
`--format <fmt>`	Output format: `text` (default), `json`

`agentboot lint`

Static analysis for prompt quality. Checks token budgets, vague language, hardcoded secrets, line counts, missing output format sections, and unused traits.

agentboot lint
agentboot lint --persona code-reviewer
agentboot lint --severity info
agentboot lint --format json

Flag	Description
`--persona <name>`	Lint a specific persona only
`--severity <level>`	Minimum severity to report: `info`, `warn` (default), `error`
`--format <fmt>`	Output format: `text` (default), `json`

Exit code 1 if any errors are found.

Lint rules

Rule	Severity	Description
`prompt-too-long`	error/warn	Token estimate exceeds budget, or line count > 500/1000
`vague-instruction`	warn	Phrases like "be thorough", "try to", "best practice"
`credential-in-prompt`	error	API keys, tokens, JWTs, hardcoded passwords
`missing-output-format`	info	No `## Output Format` section in SKILL.md
`trait-too-long`	warn	Trait exceeds 100 lines
`unused-trait`	info	Trait file exists but is not in `traits.enabled`

`agentboot export`

Export compiled output in a distributable format.

agentboot export
agentboot export --format plugin
agentboot export --format managed --output ./out
agentboot export --format agentskills
agentboot export --format agentskills --output ./skills-export

Flag	Description
`--format <fmt>`	Export format: `plugin` (default), `managed`, `agentskills`
`--output <dir>`	Output directory (defaults vary by format)

Export formats

Format	Output	Default path
`plugin`	Claude Code plugin directory	`.claude-plugin/`
`managed`	Managed settings for MDM deployment	`managed-output/`
`agentskills`	`skills-index.json` from compiled SKILL.md files (agentskills.io standard)	`dist/agentskills/`

Requires agentboot build to have been run first (for plugin, managed, and agentskills formats).

`agentboot uninstall`

Remove AgentBoot-managed files from a repository. Uses the .agentboot-manifest.json written during sync to identify managed files. Files modified after sync (hash mismatch) are skipped with a warning.

agentboot uninstall
agentboot uninstall --repo /path/to/repo
agentboot uninstall --dry-run

Flag	Description
`--repo <path>`	Target repository path (default: current directory)
`-d, --dry-run`	Preview what would be removed

`agentboot audit`

Audit the hub itself for health issues — orphaned traits, dead gotchas, and scope shadows.

agentboot audit
agentboot audit --format json

Flag	Description
`--format <type>`	Output format: `text` (default) or `json`

Hub management

AgentBoot keeps a global registry of hubs (~/.agentboot/config.json) so /ab and the MCP server can resolve a hub from any repo. Override the registry location with the AGENTBOOT_HOME environment variable (its .agentboot directory is used; handy for isolation or a non-default location).

Hub resolution order (CLI commands)

Every hub-reading CLI command resolves its hub the same way (UI-14 — previously mcp-server/doctor honored AGENTBOOT_HUB while status/drift-check ignored it):

--config <path> — explicit flag always wins.
AGENTBOOT_HUB — session-scoped hub override (points at the hub directory).
Current directory — you are in your hub.
Fallback — build scripts fall back to the package root; read-only commands (status) consult the hub registry only to suggest a hub, never to silently act on one.

Hub resolution order (`agentboot mcp-server`)

The MCP server's ladder is different, and it is different in a way that matters. It takes no --config flag, and its last two rungs act where the CLI only suggests:

AGENTBOOT_HUB — session-scoped hub override. If a registry default also exists and differs, the env var wins and the difference is reported.
Current directory — the server was started in a directory containing agentboot.config.json.
Global registry — the registry's default hub is used, not merely suggested. An MCP client has no prompt to answer, so there is nothing to suggest to; the server picks one and reports which.
Package root — no hub resolved anywhere. The server still starts, serving AgentBoot's own bundled personas and traits. Every answer it then gives describes the package, not your organization.

Rung 4 is a real failure mode for a misconfigured spoke, so it is reported on the channel you actually read. agentboot_status returns a hubResolution object:

"hubResolution": {
  "source": "package-fallback",
  "path": "/usr/local/lib/node_modules/agentboot",
  "fallback": true,
  "note": "No hub resolved from AGENTBOOT_HUB, the current directory, or the global registry — these answers describe AgentBoot's OWN bundled content, not your organization's. …"
}

source is one of env, cwd, registry, package-fallback; fallback is true only on the last. The same condition is also written to stderr — but on a stdio MCP server stderr goes to the client's log file, not to you, which is why the resolution is a returned value and not only a diagnostic. If an agent reports your org's governance and hubResolution.fallback is true, it is describing ours.

`agentboot hubs`

List registered hubs.

agentboot hubs
agentboot hubs --prune

Flag	Description
`--prune`	Remove registered hubs whose path no longer exists on disk (and clear a dead default hub)

`agentboot connect [path]`

Register a hub (the directory must contain agentboot.config.json) and set it as the default. path defaults to the current directory.

agentboot connect
agentboot connect ~/work/personas

`agentboot use <path>`

Switch the default hub to an already-registered hub.

agentboot use ~/work/personas

`agentboot config [key] [value]`

Read or write configuration values. Prints the full config, a specific dotted key path, or sets a string value.

agentboot config                    # Print full config
agentboot config org                # Print org name
agentboot config personas.enabled   # Print enabled personas list
agentboot config org my-new-org     # Set org to "my-new-org"

Writing: When a value argument is provided, the command updates agentboot.config.json in place. JSONC comments in the config file are preserved — if the file contains comments, the write is rejected with a message to edit manually (to prevent comment destruction). Only string values can be written via the CLI; arrays and objects must be edited directly.

Type safety: The CLI validates that the new value matches the expected type for the key. Writing a string to an array field (e.g., agentboot config personas.enabled foo) is rejected.

`agentboot cost-estimate`

Calculate projected monthly costs per persona across the org. Reads compiled SKILL.md files from dist/skill/core/ to estimate token counts, then applies model pricing.

agentboot cost-estimate
agentboot cost-estimate --model opus --team-size 25
agentboot cost-estimate --json

Flag	Description
`--model <model>`	Claude model: `haiku`, `sonnet`, `opus` (default: `sonnet`)
`--invocations <n>`	Invocations per persona per team member per month (default: `100`)
`--team-size <n>`	Number of team members (default: `10`)
`--json`	Output in machine-readable JSON format

Output: table showing Persona, Tokens, Monthly Invocations, and Estimated Monthly Cost. Requires dist/ to exist — run agentboot build first.

`agentboot mcp-server`

Start a Model Context Protocol (MCP) server over stdio. Exposes AgentBoot persona and trait data to any MCP-compatible client.

agentboot mcp-server                        # read-only profile (default)
agentboot mcp-server --profile maintainer   # adds build / sync / propose_change

Profiles. The default profile is read-only: inspection tools only. The mutating tools — agentboot_build, agentboot_sync, agentboot_propose_change (creates a branch, pushes, opens a PR) — are hidden from tools/list and rejected if called, unless the server is started with --profile maintainer or AGENTBOOT_MCP_PROFILE=maintainer. An autonomous MCP client wired to the default server entry cannot push branches or rewrite dist/. Every tool carries MCP annotations (readOnlyHint, destructiveHint, openWorldHint) so clients can display what mutates.

Read-only tools:

agentboot_list_personas — list available personas with names and descriptions
agentboot_get_persona — get full SKILL.md content by persona name
agentboot_list_traits — list available traits
agentboot_get_trait — get trait content by name
agentboot_list_gotchas — list gotcha rules with path patterns
agentboot_status, agentboot_list_repos, agentboot_cost_estimate, agentboot_scan_for_import, agentboot_validate, agentboot_lint, agentboot_doctor

Maintainer-profile tools:

agentboot_build — compile dist/ from source
agentboot_sync — sync compiled output to registered repos
agentboot_propose_change — branch + commit + push + open a PR (never pushes to main)

Reads from compiled dist/skill/core/ when available, falls back to core/ source files.

Which hub is it serving? The server's hub-resolution ladder differs from the CLI's — see Hub resolution order (agentboot mcp-server). Check hubResolution on agentboot_status before trusting an answer about your org; if hubResolution.fallback is true, no hub was found and the server is serving AgentBoot's bundled content.

`agentboot telemetry-inspect`

Show exactly what telemetry would be emitted under the current config: whether telemetry is enabled, the developer-identifier mode (with its privacy classification), the log path, the versioned event schema (every event type and field, flagged if it can identify a person), and one sample emission per event type. Reads config only — never touches a log.

agentboot telemetry-inspect
agentboot telemetry-inspect --config path/to/agentboot.config.json

`agentboot telemetry-ship`

Spool hash-chained telemetry events into sequence-numbered, digest-chained (optionally SSH-signed) batches and POST them to the org's own configured collector (telemetry.sink). There is no default endpoint — with no sink configured the command fails rather than sending anything anywhere.

agentboot telemetry-ship
agentboot telemetry-ship --spool-only
agentboot telemetry-ship --sink-config .claude/telemetry-sink.json

Flag	Description
`--sink-config <path>`	Explicit `telemetry-sink.json` (spoke side; default: nearest `.claude/telemetry-sink.json`)
`--log <path>`	Telemetry log to ship (default: config `logPath`, else `~/.agentboot/telemetry.ndjson`)
`--spool-only`	Build batches but do not POST (spool for a later run)

Sink resolution: the hub config's telemetry.sink when run in a hub, otherwise the synced telemetry-sink.json. When sync.signing is enabled (and the sink does not set sign: false), batch digests are signed with the sync signing key. Signing is all-or-nothing: on a signing failure nothing is spooled and the cursor does not advance — events are never shipped unsigned as a fallback. Failed batches stay in the spool for retry; exit code 1 if any batch failed to ship.

`agentboot telemetry-verify`

Verify the hash chain of a local telemetry log and/or the digest chain, sequence continuity, and signatures of shipped batches. Pass at least one of --log / --batches.

agentboot telemetry-verify --log ~/.agentboot/telemetry.ndjson
agentboot telemetry-verify --batches ./shipped --require-signed --allowed-signers ./allowed_signers

Flag	Description
`--log <path>`	NDJSON telemetry log to verify
`--batches <dir>`	Directory of batch files to verify (e.g. the spool's `shipped/` dir or the sink's store)
`--require-signed`	FAIL if any batch is unsigned or its signature does not verify — the only defense against signature stripping; set this in CI
`--allowed-signers <path>`	OpenSSH `allowed_signers` file to authenticate batch signatures against
`--signer <principal>`	Expected signer principal

The local log chain is unkeyed: it detects post-write edits, deletions, and reordering, but cannot prevent a full consistent rewrite — signed shipped batches verified with --require-signed are the tamper-evident control. Concurrent-hook forks in the log are reported as warnings, distinct from tampering. Batch verification reports sequence gaps (deleted or undelivered batches) as failures. Exit code 1 on any failed check.

`agentboot evidence-pack`

Export a signed, digest-protected evidence bundle of the org's governance state: hub provenance, enforcement manifests per platform (unprobed platforms reported as such), per-repo drift and manifest trust posture, guardrails and policy exceptions with expiry status, and shipped-telemetry chain evidence.

agentboot evidence-pack
agentboot evidence-pack --out ./evidence.json --telemetry-batches ./shipped

Flag	Description
`--out <path>`	Output file (default: `agentboot-evidence-<date>.json`)
`--telemetry-batches <dir>`	Shipped telemetry batch dir to include chain evidence for

The bundle always carries a sha256 pack digest; with sync.signing enabled it is also SSH-signed with the sync key (a configured-but-failing signer is an error, exit code 1 — never a silent fallback to unsigned). The output file is written mode 0600.

`agentboot optimize`

Analyze persona telemetry and generate optimization recommendations: aggregated usage metrics, per-persona model recommendations, and coverage-gap analysis. It reads local telemetry (~/.agentboot/telemetry/), prints a report, and can optionally write an HTML report. It does not modify persona.config.json, and needs no LLM/API provider.

What hook telemetry can and cannot feed. The generated hooks deliberately emit a minimal, content-free schema — persona id, timestamps, status; no token, cost, model, or scope fields (see agentboot telemetry-inspect). Over hook-only logs, optimize reports real invocation counts, labels the absent fields "(not collected)", and states up front that cost figures and model recommendations require API-level telemetry (events carrying cost_usd/input_tokens, e.g. from a wrapper that records API usage). A $0.00 total over hook events means "not measured", never "free".

agentboot optimize
agentboot optimize --since 2026-01-01 --until 2026-03-31
agentboot optimize --scope team:platform/*
agentboot optimize --report --output-dir ./reports
agentboot optimize --json

Flag	Description
`--since <date>`	Start date (YYYY-MM-DD)
`--until <date>`	End date (YYYY-MM-DD)
`--scope <scope>`	Filter by scope (e.g. `team:platform/*`)
`--report`	Write an HTML report to `agentboot-optimize-<date>.html`
`--output-dir <path>`	Directory for the HTML report (default: `.`)
`--json`	Output raw JSON (metrics, recommendations, gaps)

Requires telemetry to have been collected first (enable it in agentboot.config.json — see Configuration). If no telemetry is found, the command exits cleanly.

Global Options​

agentboot build​

agentboot validate​

agentboot test​

agentboot migrate​

agentboot sync​

First sync onto a repo with existing agent config​

Provenance, risk summaries, and manifest integrity​

agentboot verify-manifest​

agentboot mcp-pin​

agentboot mcp-verify​

agentboot dev-build​

agentboot install​

agentboot install-user​

agentboot import​

Org-scale sweeps and cross-repo dedup​

agentboot add <type> <name>​

Supported types​

agentboot doctor​

agentboot drift-check​

agentboot conformance​

agentboot baseline​

agentboot identity​

agentboot status​

agentboot lint​

Lint rules​

agentboot export​

Export formats​

agentboot uninstall​

agentboot audit​

Hub management​

Hub resolution order (CLI commands)​

Hub resolution order (agentboot mcp-server)​

agentboot hubs​

agentboot connect [path]​

agentboot use <path>​

agentboot config [key] [value]​

agentboot cost-estimate​

agentboot mcp-server​

agentboot telemetry-inspect​

agentboot telemetry-ship​

agentboot telemetry-verify​

agentboot evidence-pack​

agentboot optimize​