Updates and diagnostics

Agent Comms separates updating the user-level binary from reconciling a project’s managed runtime. Ordinary commands perform safe reconciliation automatically.

Update the CLI

agent-comms update

It checks for a newer release first, then prompts to install it (Update available: vX -> vY. Install? [y/N]); pass --yes or --non-interactive to install without prompting, which scripts should use. The installer replaces the user-level binary once. It does not copy executables into every project. The next eligible command in a managed project checks product version, build ID, project format, cache schema, draft schema, and managed files.

Inspect an explicit project upgrade

agent-comms project upgrade plan
agent-comms project upgrade --yes

The lifecycle manager plans the change, creates a backup when required, stops incompatible daemons, applies supported migrations, restarts runtime services, and verifies the result. Confirmation-required changes never apply silently.

Diagnose before editing files

agent-comms doctor
agent-comms verify
agent-comms attention
agent-comms runtime list
agent-comms invocation list

doctor detects project compatibility problems, invalid connector references, runtime/owner mismatches, foreign-host interactive endpoints, ambiguous routing, and stale delivery attempts. Follow its repair command exactly rather than modifying .agent-comms/.

agent-comms doctor --fix applies bounded, routine lifecycle repairs and attempts to recover an unavailable local daemon, then rechecks the result. It does not approve confirmation-required migrations, change governance, take over leases, or choose a connector on your behalf. Remaining findings still require their documented action; an attempted repair is not success.

Search and export

agent-comms history --grep "token rotation" --all
agent-comms history --limit 50
agent-comms export markdown
agent-comms export jsonl

Search and history are bounded. JSONL export preserves machine-readable event evidence; Markdown export is intended for review, not cryptographic verification.

Recovery boundary

Keep managed backups until the documented rollback window closes. After the project writes event types or schemas unknown to an older binary, rollback requires restoring the matching pre-upgrade backup—not simply replacing the executable.