CLI Reference

Detailed documentation for the agentsmd command-line interface.

Installation

The CLI is distributed as a Python package via PyPI. We recommend installing it globally or using pipx for isolation.

TerminalPython 3.13+

$pip install agentsmd

The AGENTS.md Spec

Every AgentsMD workspace is centered around an AGENTS.mdfile. This is your project's "source of truth"—a high-level Markdown specification that defines how all AI agents should behave in your codebase.

Claude CodeCLAUDE.md

Cursor.cursorrules

Windsurf.windsurfrules

Copilotgithub-copilot.xml

OpenClaw.openclaw/agents

Kimi CLIKIMI.md

agentsmdinit

Scaffolds a new agent workspace.

Initializes a new project by running an interactive interview to understand your stack, tools, and conventions. Generates a tailored AGENTS.md and relevant tool configuration files.

Syntax

$agentsmd init

Examples

# Initialize a standard workspace

$agentsmd init

agentsmdsync

Synchronize configurations across environments.

Pushes local changes to the AgentsMD cloud and pulls updates from other machines. Uses vector clocks to detect and resolve conflicts in agent instructions.

Syntax

$agentsmd sync [workspace_path]

Options

Parameter	Type / Default	Description
workspace_path	PathDefault: .	The directory to synchronize. Defaults to the current working directory.

Examples

# Sync current directory

$agentsmd sync

# Sync a specific project folder

$agentsmd sync ./my-app

agentsmdstatus

Show synchronization and drift status.

Displays whether your local AGENTS.md is in sync with the cloud and detects if derived tool files (like .cursorrules) have drifted from the source of truth.

Syntax

$agentsmd status [workspace_path]

Options

Parameter	Type / Default	Description
workspace_path	PathDefault: .	Directory to check status for.

Examples

# Check status of current workspace

$agentsmd status

agentsmdlogin

Authenticate the CLI session.

Connects your local machine to your AgentsMD account. Required for cloud synchronization features.

Syntax

$agentsmd login [--token <api_token>]

Options

Parameter	Type / Default	Description
--token, -t	stringDefault: None	Directly provide an API token (generated from the dashboard) to skip the interactive login.

Examples

# Interactive login

$agentsmd login

# Login using a token from dashboard

$agentsmd login --token amd_12345...

agentsmdmigrate

Adopt AgentsMD from existing configs.

Converts existing tool-specific configuration files into a unified AGENTS.md file. Supports importing from Claude Code, Cursor, Windsurf, and Copilot.

Syntax

$agentsmd migrate --from <format> [--to <format>] [--dry-run]

Options

Parameter	Type / Default	Description
--from	agents \| claude \| cursor \| windsurf \| copilotDefault: None	The source format to import from.
--to	stringDefault: agents	The target format to generate. Defaults to creating an AGENTS.md file.
--dry-run	booleanDefault: false	Preview the generated content in the terminal without writing any files to disk.

Examples

# Import from an existing .cursorrules file

$agentsmd migrate --from cursor

# Preview conversion from CLAUDE.md without saving

$agentsmd migrate --from claude --dry-run

agentsmdreconcile

Manually regenerate derived tool files.

Force the regeneration of all tool-specific files (CLAUDE.md, .cursorrules, etc.) based on the current state of AGENTS.md.

Syntax

$agentsmd reconcile [--from <format>]

Options

Parameter	Type / Default	Description
--from	stringDefault: auto	Manually specify which file should be treated as the source of truth for the reconciliation.

Examples

# Standard reconciliation

$agentsmd reconcile

The CanonicalModel

Internally, AgentsMD doesn't just string-replace files. It parses your Markdown into a strongly-typed CanonicalModel. This model captures the logic of your rules and allows for semantic conflict resolution and cross-tool validation.