---
draft: false
title: CLI Reference
description: Complete reference for all AgentsMesh CLI commands — init, generate, import, convert, install, uninstall, installs, refresh, diff, lint, watch, check, merge, matrix, plugin, and target. Both project and global mode supported.
sidebar:
  label: Overview
  order: 0
---

import { Card, CardGrid } from '@astrojs/starlight/components';

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

```bash
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

<CardGrid>
  <Card title="init" icon="add-document">
    Scaffold the canonical `.agentsmesh/` directory or `~/.agentsmesh/`. Detects and optionally imports existing tool configs.
    [→ init docs](./init/)
  </Card>
  <Card title="generate" icon="rocket">
    Generate target-specific config files from the canonical directory. The primary command you run after editing canonical files.
    [→ generate docs](./generate/)
  </Card>
  <Card title="import" icon="download">
    Import an existing tool's config into canonical format. Supports all targets.
    [→ import docs](./import/)
  </Card>
  <Card title="convert" icon="right-arrow">
    Convert configuration directly from one tool to another without canonical setup.
    [→ convert docs](./convert/)
  </Card>
  <Card title="install" icon="puzzle">
    Install rules, commands, agents, or skills from GitHub, GitLab, git URLs, or local paths.
    [→ install docs](./install/)
  </Card>
  <Card title="uninstall" icon="close">
    Remove an installed pack. Cleans `.agentsmesh/packs/`, `installs.yaml`, extends entries, and generated outputs.
    [→ uninstall docs](./uninstall/)
  </Card>
  <Card title="installs" icon="information">
    Read-only inventory — list installed packs with name, source, features, and install date.
    [→ installs docs](./installs/)
  </Card>
  <Card title="refresh" icon="refresh">
    Re-fetch and re-apply installed packs from their recorded sources. Branch pins advance to the current tip; SHA pins stay put. Per-pack atomic.
    [→ refresh docs](./refresh/)
  </Card>
  <Card title="diff" icon="magnifier">
    Show a unified diff of what the next `generate` would change, without writing anything.
    [→ diff docs](./diff/)
  </Card>
  <Card title="lint" icon="approve-check">
    Validate canonical files against target-specific constraints.
    [→ lint docs](./lint/)
  </Card>
  <Card title="watch" icon="refresh">
    Watch project or home canonical config and auto-regenerate on save.
    [→ watch docs](./watch/)
  </Card>
  <Card title="check" icon="warning">
    Verify sync status for CI pipelines. Exits 1 if drift is detected.
    [→ check docs](./check/)
  </Card>
  <Card title="merge" icon="list-format">
    Resolve `.agentsmesh/.lock` merge conflicts after `git merge`.
    [→ merge docs](./merge/)
  </Card>
  <Card title="matrix" icon="information">
    Display the feature-target compatibility matrix for your config.
    [→ matrix docs](./matrix/)
  </Card>
  <Card title="plugin" icon="puzzle">
    Manage runtime plugin targets — add, list, info, and remove third-party `TargetDescriptor` packages.
    [→ plugin docs](./plugin/)
  </Card>
  <Card title="target" icon="add-document">
    Scaffold a new built-in target. Generates the descriptor, generators, importer, linter, tests, and fixtures.
    [→ target docs](./target/)
  </Card>
  <Card title="lessons" icon="open-book">
    Query and capture lessons from the universal recall/capture graph. The two primitives every harness uses around edits and shell commands.
    [→ lessons docs](./lessons/)
  </Card>
</CardGrid>

## Common workflows

```bash
# 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
```
