CLI Reference

Everything agentsmd can do. Click the copy icon on any code block to grab the command.

Quick start

Four commands to get from zero to a synced workspace.

1. Install the CLI

$pip install agentsmd

2. Save your API token

$agentsmd login --token agt_xxxxxxxx

3. Initialize in your project

$agentsmd init

4. Sync after edits

$agentsmd sync

Common workflows

Three scenarios you'll hit often.

First time on a project

Run from any project folder. The CLI detects your existing agent files (or asks one question if there are none), creates a cloud workspace, and uploads everything.

$cd ~/path/to/your/project

$agentsmd init

Day-to-day editing

Edit your config files locally or via the dashboard. Sync brings both sides together. When the same file changed in both places, sync keeps the most recently edited version by default.

# edit CLAUDE.md (or whatever your tool uses)

$agentsmd sync

Setting up a second machine

Same login token, then pull the workspace into a new folder.

$agentsmd login --token agt_xxxxxxxx

$agentsmd init --from my-startup

$cd my-startup

Commands

agentsmdlogin

Save an API token to this machine.

Saves your token so subsequent commands can authenticate. Generate a token from the dashboard's Tokens page.

Syntax

$agentsmd login --token <api_token>

Options

Parameter	Type / Default	Description
--token, -t	stringDefault: required	API token from the dashboard.

Examples

# Save a token

$agentsmd login --token agt_xxxxxxxx

agentsmdinit

Create a workspace in the current folder (or clone one from the cloud).

Detects existing agent config files (CLAUDE.md, .cursorrules, .claude/, etc.) and imports them. If none are detected, asks which AI tool you use, scans your repo, and generates a single config file using a template from the cloud. Auto-pushes to the cloud at the end. Use --from to pull down a workspace that already lives in the cloud.

Syntax

$agentsmd init [--name <name>] [--from <name>] [--no-push] [--no-hide-ide]

Options

Parameter	Type / Default	Description
--name, -n	stringDefault: current folder name	Workspace name to use when creating a new workspace. Skips the interactive picker.
--from	stringDefault: —	Clone an existing cloud workspace by name into a new subfolder.
--directory, -d	PathDefault: ./<name>	Target folder for --from. Must be empty or non-existent.
--no-push	booleanDefault: false	Skip the automatic cloud upload at the end of init. Run 'agentsmd up' yourself later.
--no-hide-ide	booleanDefault: false	Skip auto-hiding the local sync folder from VS Code / Cursor / Zed / Sublime / JetBrains explorers.
--force, -f	booleanDefault: false	Overwrite the target file in generate-mode if it already exists.

Examples

# First run in a new folder

$agentsmd init

# Pull a workspace onto a second machine

$agentsmd init --from my-startup

# Initialize without auto-pushing

$agentsmd init --no-push

agentsmdsync

Bidirectional sync with the cloud.

Uploads your local changes and downloads cloud changes in one pass. If the same file changed on both sides, sync prompts per file with [L] Keep local / [C] Keep cloud / [M] Merge so you decide each outcome. Prefer silent newest-wins? Pass --auto for one run, or save 'agentsmd config set conflict.strategy auto' as your default. The losing version is always preserved as a backup.

Syntax

$agentsmd sync [workspace_path] [--interactive | --auto]

Options

Parameter	Type / Default	Description
workspace_path	PathDefault: current directory	The folder to sync. Defaults to your cwd.
--interactive / --auto, -i	booleanDefault: prompt (interactive)	Force the [L]/[C]/[M] prompt for one run (--interactive) or force silent newest-wins (--auto). If neither flag is given, the CLI uses your saved conflict.strategy preference, which defaults to interactive.

Examples

# Sync the current folder

$agentsmd sync

# Force prompts for this run

$agentsmd sync --interactive

# Force silent newest-wins for this run

$agentsmd sync --auto

agentsmdstatus

Preview what sync would do.

Shows what's pending: uploads, downloads, and conflicts. Nothing is written. Use it before a sync when you're unsure of the state.

Syntax

$agentsmd status [workspace_path]

Options

Parameter	Type / Default	Description
workspace_path	PathDefault: current directory	The folder to check.

Examples

# Check current folder

$agentsmd status

agentsmdresolve

Redo a past conflict outcome for one file.

If sync auto-resolved a conflict the wrong way (because you passed --auto, set conflict.strategy auto, or ran sync in a non-TTY like CI), run resolve on that file. The CLI loads the backed-up version, shows the [L] Keep local / [C] Keep cloud / [B] Keep both / [M] Merge prompt, applies your choice, and pushes the result.

Syntax

$agentsmd resolve <path>

Options

Parameter	Type / Default	Description
path	stringDefault: required	Relative path of the file to re-decide (e.g. CLAUDE.md).

Examples

# Flip a CLAUDE.md decision

$agentsmd resolve CLAUDE.md

agentsmdlist

Show your cloud workspaces.

Lists every workspace owned by the authenticated account, with last-sync time and short id.

Syntax

$agentsmd list

Examples

# List all workspaces

$agentsmd list

agentsmdlink

Bind or unbind a folder to a cloud workspace.

Binds this folder to the named cloud workspace. Use --remove to clear the binding without affecting the cloud workspace itself.

Syntax

$agentsmd link <name> | agentsmd link --remove

Options

Parameter	Type / Default	Description
name	stringDefault: —	Workspace name to bind this folder to.
--remove	booleanDefault: false	Remove the local binding. Cloud workspace is preserved.

Examples

# Bind current folder

$agentsmd link my-startup

# Unlink (cloud workspace stays)

$agentsmd link --remove

agentsmddelete

Delete a cloud workspace and its files.

Deletes the workspace and its files from the cloud. If the folder you're standing in is bound to the workspace you're deleting, the local binding is also removed.

Syntax

$agentsmd delete <name> [--force]

Options

Parameter	Type / Default	Description
name	stringDefault: required	Workspace name to delete.
--force, -f	booleanDefault: false	Skip the confirmation prompt.

Examples

# Delete with confirmation

$agentsmd delete my-old-workspace

# Delete without prompt (scripts)

$agentsmd delete my-old-workspace --force

agentsmdconfig

Read or write user preferences.

Currently the only validated key is conflict.strategy. Set it to 'auto' to make sync silently pick the newer side, or 'interactive' to get the [L]/[C]/[M] prompt every time. Leaving it unset keeps the interactive default.

Syntax

$agentsmd config get <key> | agentsmd config set <key> <value> | agentsmd config unset <key> | agentsmd config list

Options

Parameter	Type / Default	Description
<key>	stringDefault: —	Preference key (currently only conflict.strategy).
<value>	stringDefault: —	Allowed values for conflict.strategy: auto \| interactive.

Examples

# Always auto-resolve conflicts (no prompt)

$agentsmd config set conflict.strategy auto

# Always prompt per conflict

$agentsmd config set conflict.strategy interactive

# Back to default (prompt per conflict)

$agentsmd config unset conflict.strategy

# Show all preferences

$agentsmd config list

agentsmdconvert

Translate between AI tool config formats.

Converts a single source format (e.g. .cursorrules) into other tools (e.g. CLAUDE.md, .windsurfrules), or use --reconcile to re-derive every detected format from the source of truth (AGENTS.md by default).

Syntax

$agentsmd convert --from <format> [--to <format>] [--dry-run] | agentsmd convert --reconcile

Options

Parameter	Type / Default	Description
--from	agents \| claude \| cursor \| windsurf \| copilotDefault: —	Source format to convert from. Required unless --reconcile is set.
--to	stringDefault: all formats	Target format. Defaults to deriving every supported format.
--reconcile	booleanDefault: false	Auto-detect the source and re-derive every other detected format.
--dry-run	booleanDefault: false	Preview the result without writing files.

Examples

# Convert Cursor rules to every other format

$agentsmd convert --from cursor

# Just Claude to Cursor

$agentsmd convert --from claude --to cursor

# Preview without writing

$agentsmd convert --from cursor --dry-run

# Re-derive every detected format from AGENTS.md

$agentsmd convert --reconcile

agentsmdup

Upload local changes only.

Pushes local file changes to the cloud workspace. Never modifies local files, never downloads. Useful for CI scripts where you want a guaranteed one-direction operation.

Syntax

$agentsmd up [workspace_path]

Options

Parameter	Type / Default	Description
workspace_path	PathDefault: current directory	The folder to upload.

Examples

# Upload current folder

$agentsmd up

agentsmddown

Download cloud changes only.

Pulls the cloud version, overwriting local. Never uploads. Useful for disaster recovery when you want exactly what's in the cloud.

Syntax

$agentsmd down [workspace_path]

Options

Parameter	Type / Default	Description
workspace_path	PathDefault: current directory	The folder to download into.

Examples

# Pull cloud copy into current folder

$agentsmd down

agentsmdrestore

Undo the last sync, up, or down.

Replays the single-slot backup created automatically before any sync operation. Useful when you regret a download that clobbered local edits, or when a sync produced unexpected files.

Syntax

$agentsmd restore [workspace_path] [--dry-run]

Options

Parameter	Type / Default	Description
workspace_path	PathDefault: current directory	The folder to restore.
--dry-run	booleanDefault: false	Preview what would be restored without writing.

Examples

# Undo last sync

$agentsmd restore

# See what restore would do first

$agentsmd restore --dry-run

agentsmdlogout

Clear local credentials.

Clears your saved token. Local workspace bindings are left alone.

Syntax

$agentsmd logout

Examples

# Sign out from this machine

$agentsmd logout

Workspaces

A workspace is a named set of agent config files that lives in your AgentsMD cloud account. Each local folder is bound to one workspace, so commands like sync know what to push and pull.

You can rename or move the folder freely. The binding follows the directory. Free accounts get 1 workspace; Pro unlocks unlimited.

Agent config files we recognize

agentsmd init detects whichever of these your project already uses, and syncs them as-is. When generating from scratch, it asks which tool you primarily use and writes only that file.

Claude CodeCLAUDE.md, .claude/

Cursor.cursorrules, .cursor/rules/

GitHub Copilot.github/copilot-instructions.md

Windsurf.windsurfrules, .windsurf/rules/

OpenCode / CodexAGENTS.md

AiderCONVENTIONS.md, .aider.conf.yml

Cline.clinerules

Continue.continue/

Zed.rules

Kimi CLIKIMI.md, .kimi/

Conflict handling

When the same file changed on both sides since the last sync, agentsmd sync prompts you per file by default with [L] Keep local / [C] Keep cloud / [M] Merge. No silent overwrites — you decide each one. If only one side changed, sync just applies it; the prompt only appears for real conflicts.

Prefer silent newest-wins instead? The more recently edited version is kept and the loser is preserved as a backup under .agentsmd/conflicts/. Switch the default once:

$agentsmd config set conflict.strategy auto

To go back to the prompt (or override your saved preference for a single run), use:

$agentsmd config unset conflict.strategy

$agentsmd sync --interactive

$agentsmd sync --auto

Non-TTY shells (e.g. CI) always fall back to newest-wins automatically — there's no terminal to prompt. If auto-resolve (yours or CI's) picked the wrong side, run agentsmd resolve <path>. You'll get a [L] [C] [B] [M] prompt to flip the decision and push it.