Skip to main content

CLI Commands

Complete v0.1 reference for the agentmesh CLI.

Global flags​

Apply to every command unless noted:

FlagPurpose
-h, --helpShow help and exit 0
-V, --versionPrint version and exit 0
--silentSuppress informational output; errors still print to stderr
--no-colorDisable ANSI colors (NO_COLOR=1 equivalent)
--color=auto|always|neverOverride color behavior
--cwd=<path>Run as if invoked from <path>
-v, --verboseMore detail; -vv for debug

agentmesh init​

One-time repository setup. Idempotent — safe to re-run.

What it does:

  1. Scans for Claude and Codex artifacts
  2. Imports entities into .ai/ canonical model
  3. Propagates to other detected runtimes
  4. Installs hooks (unless --skip-hooks)
  5. Writes agentmesh.lock
FlagPurpose
--canonical-instructions=AGENTS.mdNon-interactive: use AGENTS.md as the starting agent memory file during init
--canonical-instructions=CLAUDE.mdNon-interactive: use CLAUDE.md as the starting agent memory file during init
-y, --yesSkip confirmation prompts
--dry-runPreview without writing
--skip-hooksCanonical state + lockfile only

agentmesh install​

Install hooks for a runtime or git pre-commit safety net.

FlagPurpose
--runtime <name>Install hooks for claude or codex
--git-pre-commitInstall pre-commit drift check
--forceWith --git-pre-commit: overwrite framework-managed hooks
-y, --yesSkip confirmation
--dry-runPreview without writing

When to use install vs init:

SituationCommand
First setup with runtimes presentagentmesh init
Added .codex/ after Claude-only initagentmesh install --runtime codex
Ran init --skip-hooks, now want hooksagentmesh install --runtime claude (and/or codex)
Want commit-time drift checkagentmesh install --git-pre-commit

agentmesh start​

Start AgentMesh again for an already initialized repository.

Use this after agentmesh stop, or when local hooks need to be restored on a machine that already has agentmesh.lock.

What it does:

  1. Reads existing repository state from agentmesh.lock
  2. Refreshes machine-local AgentMesh state for this repo
  3. Reinstalls AgentMesh-owned hooks for detected runtimes

It does not create new canonical repository state. For first-time setup, use agentmesh init.

FlagPurpose
--dry-runPreview without writing
-y, --yesSkip confirmation prompts

agentmesh stop​

Stop AgentMesh for this repository only while keeping shared repository state.

What it does:

  1. Stops the watcher for this repo
  2. Removes AgentMesh-owned hooks for this repo
  3. Clears machine-local AgentMesh state for this repo

What it keeps:

  • The agentmesh binary
  • agentmesh.lock
  • .ai/
  • agentmesh.config.yaml
  • Runtime files such as AGENTS.md and CLAUDE.md
FlagPurpose
--dry-runPreview without writing
-y, --yesSkip confirmation prompts

agentmesh status​

Fast snapshot (under 50ms). Exit 0 if healthy.

AgentMesh 0.1.0   repo: my-repo   lockfile: schema 1 (current)
  hooks:    claude ✓   codex ✓
  watcher:  not running (lazy-start active)
  pending:  0 in queue
  conflicts: 0 unresolved
  integrity: ✓

For details, use doctor.

agentmesh scan​

Read-only detection of runtimes and entities. No writes. Exit 0.

Use before init to see what AgentMesh will import.

agentmesh sync​

Manual sync pass. Usually automatic via hooks.

FlagPurpose
--checkDry-run for CI — exit non-zero on any drift
--await-drainBlock until async fan-out completes
--trigger=<source>Origin hint: claude-hook, codex-hook, watcher, cli

sync --check exit codes​

ExitMeaning
0Lockfile matches filesystem
1Drift detected (any state movement)
2Strict CI rule violated
3Integrity failure
4Unsupported lockfile schema

agentmesh diff / agentmesh apply​

diff — preview what sync would change (exit 1 if changes pending).

apply — write changes after reviewing diff.

agentmesh doctor​

Deep health check. Slower than status but exhaustive.

FlagPurpose
--versionsPrint binary, adapter, protocol, schema versions
--integrity-onlyFast integrity check only
--watcher-onlyWatcher status only
--jsonMachine-readable output

Surfaces: adapter health, hook integrity, lockfile state, pending conflicts with recovery commands, gitignore warnings.

agentmesh restore​

Recover a losing version from an auto-resolved conflict.

agentmesh restore skill:security-review --from codex
FlagPurpose
--from <runtime>Required: ai, claude, or codex
--at <timestamp>Specific conflict timestamp if multiple exist
--dry-runPreview without writing

agentmesh ack​

Acknowledge a pending_conflict_resolution flag without restoring.

agentmesh ack skill:security-review
agentmesh ack              # all pending (with confirmation)

agentmesh watch​

Start the watcher daemon explicitly.

FlagPurpose
--persistentNo idle exit
--register-as-serviceRegister LaunchAgent/systemd/Task Scheduler
--foregroundDon't detach
-y, --yesSkip service registration confirmation

Default idle timeout: 30 minutes.

agentmesh upgrade​

Repin integrity to the currently-installed binary. Rewrites hook entries if the path changed.

Run after upgrading the AgentMesh binary via the installer or a local rebuild.

FlagPurpose
--dry-runPreview
-y, --yesSkip confirmation

agentmesh uninstall​

Remove AgentMesh-owned state from this repository.

What it does:

  1. Runs the same repository-local cleanup as agentmesh stop
  2. Deletes agentmesh.lock
  3. Deletes .ai/
  4. Deletes agentmesh.config.yaml

What it keeps:

  • The installed agentmesh command, unless --full is passed
  • Runtime files such as AGENTS.md and CLAUDE.md
  • Runtime-owned folders and settings that AgentMesh did not create

To also remove AgentMesh from the computer, run:

agentmesh uninstall --full
FlagPurpose
--fullAlso remove the installed AgentMesh command
--dry-runPreview
-y, --yesSkip confirmation

agentmesh reconcile-lock​

Recover from a textual git merge conflict in agentmesh.lock. Does not auto-commit.

agentmesh reconcile-lock
git diff agentmesh.lock
git add agentmesh.lock && git commit

Hidden commands​

Not listed in --help:

CommandPurpose
agentmesh __adapter <name> --stdioInternal adapter JSON-RPC mode

v0.2+ reserved commands​

Invoking these prints "available in v0.2+":

  • agentmesh graph
  • agentmesh adapter add/remove/list/update