CLI Reference

AgentsMesh ships a CLI available as agentsmesh and the short alias amsh.

agentsmesh --help
amsh --help

Global flags

Flag	Description
--help	Show help output and exit.
--version	Print CLI version and exit.
--verbose	Show full error stack traces on failure.
--json	Output machine-readable JSON (single envelope to stdout). Not supported with watch.

Commands

init

Scaffold the canonical .agentsmesh/ directory or ~/.agentsmesh/. Detects and optionally imports existing tool configs. → init docs

generate

Generate target-specific config files from the canonical directory. The primary command you run after editing canonical files. → generate docs

import

Import an existing tool’s config into canonical format. Supports all targets. → import docs

convert

Convert configuration directly from one tool to another without canonical setup. → convert docs

install

Install rules, commands, agents, or skills from GitHub, GitLab, git URLs, or local paths. → install docs

diff

Show a unified diff of what the next generate would change, without writing anything. → diff docs

lint

Validate canonical files against target-specific constraints. → lint docs

watch

Watch project or home canonical config and auto-regenerate on save. → watch docs

check

Verify sync status for CI pipelines. Exits 1 if drift is detected. → check docs

merge

Resolve .agentsmesh/.lock merge conflicts after git merge. → merge docs

matrix

Display the feature-target compatibility matrix for your config. → matrix docs

plugin

Manage runtime plugin targets — add, list, info, and remove third-party TargetDescriptor packages. → plugin docs

target

Scaffold a new built-in target. Generates the descriptor, generators, importer, linter, tests, and fixtures. → target docs

Common workflows

# Initial setup
agentsmesh init
agentsmesh generate

# Personal/global setup
agentsmesh init --global
agentsmesh import --global --from claude-code
# Any other target that supports global mode is also valid — see the supported tools matrix.
agentsmesh generate --global

# Day-to-day editing
# 1. Edit .agentsmesh/ files
agentsmesh diff          # preview changes
agentsmesh generate      # apply changes

# Or use watch mode during active editing
agentsmesh watch

# CI pipeline
agentsmesh check         # exits 1 if out of sync

# After git merge with conflicts
agentsmesh merge         # rebuild lock from current state
agentsmesh generate