CLI Overview
Most days, no command runs. Sync happens via runtime hooks after you edit skills or instructions in Claude Code or Codex.
The CLI exists for:
- Setup —
init,install,start - Inspection —
status,scan,doctor,diff - Recovery —
restore,ack,reconcile-lock - CI —
sync --check - Maintenance —
stop,upgrade,uninstall
Command quick reference
| Command | When to use |
|---|---|
agentmesh init | First-time repo setup |
agentmesh install --runtime <name> | Runtime added after init; install its hooks |
agentmesh install --git-pre-commit | Optional commit-time drift check |
agentmesh start | Start AgentMesh again for this repo |
agentmesh stop | Stop AgentMesh for this repo only |
agentmesh status | Quick health snapshot (under 50ms) |
agentmesh scan | Read-only: what's detected before init |
agentmesh doctor | Deep health check with recovery hints |
agentmesh diff / apply | Preview / apply pending sync changes |
agentmesh sync | Manual sync (rare); sync --check for CI |
agentmesh restore <id> --from <runtime> | Recover losing version after conflict |
agentmesh ack <id> | Acknowledge conflict without restoring |
agentmesh reconcile-lock | Fix git merge conflict in lockfile |
agentmesh upgrade | Repin hooks after binary upgrade |
agentmesh uninstall | Remove AgentMesh-owned state from this repo |
agentmesh uninstall --full | Also remove AgentMesh from this computer |
agentmesh watch | Start watcher daemon explicitly |
Full details: CLI Commands.
Global flags
| Flag | Purpose |
|---|---|
-h, --help | Show help |
-V, --version | Print version |
--silent | Errors only (used by hooks) |
-v, --verbose | More detail (-vv for debug) |
--no-color | Disable ANSI colors |
--cwd=<path> | Run as if from <path> |
Exit codes
CI scripts can rely on these stable exit codes:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Drift detected (sync --check) |
| 2 | Strict-mode CI rule violated |
| 3 | Integrity check failed |
| 4 | Lockfile schema unsupported — upgrade AgentMesh |
| 5 | Invalid agentmesh.config.yaml |
| 6 | Adapter error |
| 7 | I/O error |
| 10 | Cancelled (e.g., init prompt in non-TTY) |
| 64 | Usage error (bad flag / missing argument) |
Output conventions
| Marker | Meaning |
|---|---|
✓ | Success |
⚠ | Needs attention |
✗ | Failure |
→ | Step in progress |
Typical workflows
First setup
agentmesh scan
agentmesh init
agentmesh doctor
Something looks wrong
agentmesh status # fast check
agentmesh doctor # detailed diagnosis + recovery commands
agentmesh diff # what would sync change?
After upgrading AgentMesh
agentmesh upgrade # repin binary path in hooks
agentmesh doctor # verify
Temporarily stop AgentMesh for this repo
agentmesh stop
agentmesh start # restore local hooks later
CI pipeline
agentmesh sync --check
See CI Integration.
Related
- CLI Commands — full per-command reference
- Quick Start — setup walkthrough