Command reference

Every mdm command, subcommand, alias, and flag. For a narrative walkthrough of any command, follow the "Details" links to the dedicated guide pages.

Global flags

These persistent flags are available on every command:

Flag	Description
--verbose, -v	Print diagnostic steps to stderr
--help, -h	Show help for the command
--version	Print the mdm version (root command only)

Command tree

mdm
├── upgrade                                 # Self-update the binary (aliases: update-cli, self-update)
├── uninstall                               # Remove the binary (alias: remove-cli)
├── bug                                     # Open a prefilled bug-report form (no network I/O)
├── doctor                                  # Health-check skills, agents, bundles, plugins & markdown
├── completion [bash|zsh|fish|powershell]   # Generate shell completion
│   └── install                             # Write completion into your shell rc
├── skills                                  # Manage skills for AI harnesses
│   ├── add <package>                       # Install a skill (alias: a)
│   ├── cherry-pick [source]                # Fork skills into ./skills as your own (aliases: fork, cp)
│   ├── remove [skills...]                  # Uninstall skills (aliases: rm, r)
│   ├── list                                # List installed skills (alias: ls)
│   ├── find [query]                        # Search skills.sh and install interactively (aliases: search, f, s)
│   ├── update [skills...]                  # Re-fetch from recorded source+ref (alias: check)
│   ├── audit [skills...]                   # Check for updates & security advisories
│   ├── init [name]                         # Scaffold a new SKILL.md
│   ├── install                             # Restore all skills, then agent definitions, from mdm.lock
│   └── sync                                # Sync skills from node_modules
├── knowledge                               # Manage OKF knowledge bundles
│   ├── add <source>                        # Install a bundle (alias: a)
│   ├── remove [bundles...]                 # Remove bundles (aliases: rm, r)
│   ├── list                                # List installed bundles (alias: ls)
│   ├── update [bundles...]                 # Re-fetch bundles
│   ├── validate [path]                     # Check OKF conformance & links
│   ├── init [name]                         # Scaffold a minimal bundle
│   └── install                             # Restore bundles from mdm.lock
├── plugins                                 # Manage Agent Plugins
│   ├── add <source>                        # Install a plugin, link skills, wire MCP (alias: a)
│   ├── remove [plugins...]                 # Remove plugins (aliases: rm, r)
│   ├── list                                # List installed plugins (alias: ls)
│   ├── update [plugins...]                 # Re-fetch plugins
│   ├── validate [path]                     # Check Agent Plugins conformance
│   ├── init [name]                         # Scaffold a minimal plugin
│   └── install                             # Restore plugins from mdm.lock
├── migrate                                 # Fold v1 lock files into mdm.lock / mdm-state.json
├── experimental                            # Manage experimental features
│   ├── list                                # Show features and status (alias: ls)
│   ├── enable <feature>                    # Persist an opt-in
│   └── disable <feature>                   # Remove a persisted opt-in
├── harnesses                               # Manage the configured harness list
│   ├── list                                # Show configured harnesses (alias: ls)
│   ├── add [harnesses...]                  # Add harnesses (interactive with no args, alias: a)
│   └── remove [harnesses...]               # Remove harnesses & their unique files (aliases: rm, r)
├── agents                                  # Manage agent definitions installed into harnesses
│   ├── add <source>                        # Install agent definitions (alias: a)
│   ├── list                                # List installed agent definitions (alias: ls)
│   ├── remove [names...]                   # Remove agent definitions (aliases: rm, r)
│   ├── update [names...]                   # Re-fetch agent definitions from recorded source+ref
│   └── install                             # Restore agent definitions from mdm.lock
└── rules                                   # Manage harness instruction files
    ├── link                                # Symlink instruction files to one AGENTS.md
    ├── status                              # Show which files exist/are symlinked/missing
    └── unlink                              # Remove symlinks, restore per-harness files

---

mdm skills

Manage skills - reusable markdown prompt libraries - for your AI harnesses.

skills add alias: a

Install a skill from GitHub, GitLab, a URL, or a local path.

mdm skills add <package>

<package> accepts GitHub shorthand (owner/repo), full GitHub/GitLab URLs, a git URL with a #ref, a local path, or a well-known alias (vercel, anthropic).

Flag	Description
--global, -g	Install globally (user-level, ~/.agents/skills/)
--project, -p	Force project-scope install
--harness	Harnesses to install to (repeatable; * for all)
--skill, -s	Skill names to install (repeatable; * for all)
--list, -l	List available skills without installing
--yes, -y	Skip confirmation prompts
--copy	Copy files instead of symlinking; switches the scope to copy mode
--symlink	Symlink files from .agents/skills (the default); switches a scope back from copy mode
--all	Install every skill to every harness without prompting (shorthand for --skill '*' --harness '*' -y)
--full-depth	Search all subdirectories for skills
--skip-audit	Skip the security audit check for public skills
--fail-on-audit	Exit non-zero on security findings instead of prompting
--allow-hidden-chars	Allow markdown files with hidden Unicode characters

Details

skills cherry-pick aliases: fork, cp

Fork third-party skills into ./skills so you can edit them and ship them as your own. Unlike skills add, nothing updates them afterwards - the copy is yours, with its provenance and license recorded inside it.

mdm skills cherry-pick [source]

Flag	Description
--dir, -d	Directory to fork into (default skills)
--skill, -s	Skill names to fork (repeatable; * for all)
--as	Rename the forked skill (single skill only)
--install, -i	Also install the forks into your harnesses
--harness	Harnesses to install the forks to (implies --install)
--force	Replace an existing fork, discarding local edits
--dry-run	Show what would be forked without writing anything
--list, -l	List the skills available at the source without forking
--status	Show this project's forks and whether they have been edited
--no-attribution	Do not write ATTRIBUTION.md
--full-depth	Search all subdirectories for skills
--allow-hidden-chars	Allow markdown files with hidden Unicode characters
--global, -g / --project, -p	Scope for --install (global, or this project only)
--copy / --symlink	Install mode for --install; switches the scope's mode like skills add
--yes, -y	Skip confirmation prompts

Details

skills remove aliases: rm, r

Uninstall one or more skills.

mdm skills remove [skills...]

Flag	Description
--global, -g	Remove from global scope
--harness	Remove from specific harnesses (repeatable)
--skill, -s	Skill names to remove (repeatable)
--yes, -y	Skip confirmation prompts
--all	Remove every skill without prompting (shorthand for --skill '*' -y)

--harness is scoped: it removes that harness's copy and keeps the canonical directory and the lock entry while any harness outside the filter still has the skill. With no --harness, the skill is removed outright and the sweep covers every harness, not only the ones it was detected in.

Details

skills list alias: ls

List installed skills.

mdm skills list

Flag	Description
--global, -g	List global skills
--project, -p	List project skills
--harness	Filter by specific harnesses (repeatable)
--json	Output as JSON

Details

skills find aliases: search, f, s

Search the skills.sh registry and install interactively.

mdm skills find [query]

Flag	Description
--json	Output results as JSON without installing
--source	List skills available at a remote source without installing

Details

skills update alias: check

Re-fetch skills from their recorded source and ref in the lock file.

mdm skills update [skills...]

Flag	Description
--global, -g	Update global skills only
--project, -p	Update project skills only
--yes, -y	Skip the scope prompt
--allow-hidden-chars	Allow markdown files with hidden Unicode characters

Details

skills audit

Check installed skills for available updates and OSV security advisories.

mdm skills audit [skills...]

Flag	Description
--global, -g	Audit global skills only
--project, -p	Audit project skills only
--json	Output as JSON
--source, -r	Pre-install audit: owner/repo or URL to audit before installing
--skill, -s	Skill name to audit (use with --source)

Details

skills init

Scaffold a new SKILL.md in the current directory.

mdm skills init [name]

Details

skills install

Restore all skills, then any agent definitions, from mdm.lock - ideal for CI and onboarding.

mdm skills install

Flag	Description
--yes, -y	Skip confirmation prompts
--copy	Copy files instead of symlinking; switches the scope to copy mode
--symlink	Symlink files from .agents/skills (the default); switches a scope back from copy mode
--allow-hidden-chars	Allow markdown files with hidden Unicode characters

Details

skills sync

Sync skills from node_modules into each harness's skill directories.

mdm skills sync

Flag	Description
--yes, -y	Skip confirmation prompts
--allow-hidden-chars	Allow markdown files with hidden Unicode characters

Details

---

mdm rules

Manage harness instruction files (CLAUDE.md, AGENTS.md, .cursorrules, and friends) by pointing them all at a single source of truth.

Command	Description
rules link	Symlink all harness instruction files to one AGENTS.md
rules status	Show which instruction files exist, are symlinked, or missing
rules unlink	Remove symlinks and restore per-harness instruction files

Flag (on link / status / unlink)	Description
--harness	Limit to specific harnesses (repeatable)
--json	Output status as a JSON array (status)
--yes, -y	Skip the confirmation prompt (link: replace existing real files; unlink)

Details

---

mdm harnesses

Manage the configured harness list used as default install targets. Works at both project and global scope.

Command	Description
harnesses list (ls)	Show configured harnesses for the current scope
harnesses add [harnesses...] (a)	Add harnesses (interactive picker with no args)
harnesses remove [harnesses...] (rm, r)	Remove harnesses and their unique skill/instruction files

Flag	Applies to	Description
--global, -g	all	Operate on the global configured-harness list
--json	list	Output as JSON
--available	list	List all harnesses known to mdm, not just configured ones
--yes, -y	remove	Skip confirmation prompts

Details

---

mdm agents

Manage agent definitions - single markdown or TOML files that give a harness a named subagent persona, installed into each target harness's own agent directory. Distinct from mdm harnesses above, which manages the AI tools themselves.

Command	Description
agents add <source> (a)	Install agent definitions from GitHub, a URL, or a local path
agents list (ls)	List installed agent definitions
agents remove [names...] (rm, r)	Remove installed agent definitions
agents update [names...]	Update installed agent definitions
agents install	Restore agent definitions from mdm.lock

Flag	Applies to	Description
--global, -g	add / list / remove / update	Operate on the global scope (install restores both scopes)
--project, -p	add / list / remove / update	Force project scope
--json	list	Output as a JSON array (name, scope, source, ref, canonicalMissing, installedIn, missingFrom)
--harness	add / remove	Harnesses to target (repeatable, use * for all)
--agent, -a	add / remove	Agent definition names to target (repeatable, use * for all)
--copy / --symlink	add / install	Switch the scope's install mode (see Install mode)
--force	add	Replace a definition already installed under the same name from another source
--allow-hidden-chars	add / update / install	Allow markdown files with hidden Unicode characters
--yes, -y	add / remove / update / install	Skip confirmation prompts

remove and update act on the harnesses the lock records for a definition, and within those touch only files mdm wrote: a file you placed at the same path yourself is reported and left alone. See Only files mdm wrote are removed.

Details

---

mdm knowledge

Manage Open Knowledge Format (OKF) bundles.

Command	Description
knowledge add <source> (a)	Install a bundle into ./knowledge/ and record it
knowledge remove [bundles...] (rm, r)	Remove bundles and their lock entries
knowledge list (ls)	List installed bundles
knowledge update [bundles...]	Re-fetch bundles from their recorded source+ref
knowledge validate [path]	Check OKF conformance and link integrity
knowledge init [name]	Scaffold a minimal conformant bundle
knowledge install	Restore all bundles from mdm.lock

Flag	Applies to	Description
--dir	add	Directory to install bundles into (relative to project root, default knowledge)
--bundle, -b	add	Bundle names to install (repeatable; * for all)
--dry-run	add	Show what would be installed without writing anything
--yes, -y	add / remove	Skip confirmation prompts (add: install every discovered bundle)
--json	validate	Print the validation report as JSON
--json	list	Output as a JSON array (name, source, ref, specVersion, installDir, documents, present)
--allow-hidden-chars	add / update / install	Allow markdown files with hidden Unicode characters

Details

---

mdm plugins

Manage Agent Plugins - portable packages of skills and MCP servers following the vendor-neutral agent-plugins.org standard.

Command	Description
plugins add <source> (a)	Install a plugin into .agents/plugins/, link its skills, wire its MCP servers
plugins remove [plugins...] (rm, r)	Unwire MCP, unlink skills, delete the plugin and its lock entry
plugins list (ls)	List installed plugins
plugins update [plugins...]	Re-fetch plugins from their recorded source+ref (preserves the data dir)
plugins validate [path]	Check Agent Plugins spec conformance
plugins init [name]	Scaffold a minimal conformant plugin
plugins install	Restore all plugins from mdm.lock

Flag	Applies to	Description
--plugin, -p	add	Plugin names to install (repeatable; * for all)
--harness	add	Harnesses to install for (repeatable)
--skip-mcp	add / update / install	Install skills only; do not write MCP config
--dry-run	add	Show what would be installed without writing anything
--purge-data	remove	Also delete the plugin's persistent data directory
--with-mcp	init	Also scaffold an example mcp.json
--yes, -y	add / remove	Skip confirmation prompts (add: install every discovered plugin)
--json	validate	Print the validation report as JSON
--json	list	Output as a JSON array (name, version, source, ref, specVersion, installDir, skills, harnesses, mcpServers, valid)
--allow-hidden-chars	add / update / install	Allow markdown files with hidden Unicode characters

Details

---

mdm experimental

Toggle experimental feature gates. Features can also be enabled via the MDM_EXPERIMENTAL environment variable (comma-separated names, or all).

Command	Description
experimental list (ls)	Show experimental features and their status
experimental enable <feature>	Persist an opt-in
experimental disable <feature>	Remove a persisted opt-in

This release ships no experimental features - knowledge and plugins graduated to full support in v2.

Details

---

mdm migrate

Fold the v1 lock files into the v2 layout: skills-lock.json, knowledge-lock.json, and plugins-lock.json become one mdm.lock at the project root, and the global ~/.agents/skills-lock.json becomes ~/.agents/mdm-state.json.

mdm migrate --dry-run   # show the plan
mdm migrate -y          # migrate without prompting

Non-interactive runs (CI, pipes) need --yes - without it the command fails rather than silently doing nothing.

skills-lock.json is replaced with a tombstone that points v1 users at mdm.lock - interactive runs offer to delete it outright instead. Patched v1 releases refuse the tombstone with an "upgrade mdm" error; older v1 releases read it as an empty lock, and if one of them then runs skills add it rewrites the file as a v1 lock that v2 and mdm migrate still read. Commit the new lock and the removals together. v2 reads the v1 files transparently until you migrate, but only ever writes the new ones, and mdm doctor flags projects that still carry v1 files. mdm upgrade offers to run this for you when an upgrade crosses a major version.

Migration also records the install mode, for the project and for this machine's global state. It reads the skills sitting at each configured harness's install directory, or, when no harnesses are recorded (which is what a non-interactive mdm skills add --harness <harness> -y leaves behind), at the install directory of every harness the scope supports. A real directory holding a SKILL.md means the scope was installed with --copy, so migrating sets installMode: copy in mdm.lock (or mdm-state.json) and later restores preserve them. Symlinks there mean the default mode, and nothing is recorded; so does a directory with no SKILL.md, which is someone else's, not an mdm install. The shared .agents/skills directory is deliberately not consulted: symlink installs create it as a real directory too, so it cannot tell the two modes apart.

This also covers a scope that already migrated before this existed: if its lock has no install mode recorded yet, mdm migrate backfills it from what's on disk, even when there are no legacy files left to retire. --dry-run names the mode it would record before anything is written.

Flag	Description
--dry-run	Show what would be migrated without changing anything
--yes, -y	Skip the confirmation prompt
--no-tombstone	Delete skills-lock.json instead of leaving a tombstone
--force	Discard legacy entries missing from an existing mdm.lock (they are listed first)

---

mdm bug

Report a bug with environment details prefilled. Collects the mdm version, OS/architecture, shell, Go runtime, and the AI harnesses detected on this machine, builds a GitHub issue-form URL with those fields filled in, prints it, and opens it when a browser is available.

Nothing is sent anywhere: mdm does no network I/O and no telemetry, and this command doesn't change that - it only constructs a URL; you review and submit the form yourself. $HOME is scrubbed to ~ in every value, and no repository names or usernames are included. On a crash, mdm prints the same prefilled URL automatically with the panic captured (the full output goes to a temp file for manual attachment, keeping the URL short).

mdm bug                                        # open the prefilled form
mdm bug --command "mdm skills add owner/repo"  # include the failing command
mdm bug --print                                # review everything before any browser opens

Flag	Description
--print	Print the issue body and URL to stdout without opening a browser
--command	The mdm command that failed, included in the report

Headless environments (SSH, containers, WSL2 without a browser bridge) always get the URL printed even when nothing can open it.

---

mdm doctor

Check installed skills, agent definitions, knowledge bundles, plugins, and project markdown for health issues - broken symlinks, hash mismatches, OKF and plugin conformance errors, MCP config drift, leftover v1 lock files, missing READMEs, and oversized markdown files.

mdm doctor

Flag	Description
--global, -g	Check global skills only
--project, -p	Check project skills only

Details

---

mdm upgrade aliases: update-cli, self-update

Download and replace the mdm binary from GitHub releases.

mdm upgrade

Flag	Description
--beta	Upgrade to the latest beta/prerelease version
--stable	Upgrade to the latest stable version (default)

Details

---

mdm uninstall alias: remove-cli

Remove the mdm binary from your system.

mdm uninstall

Flag	Description
--yes, -y	Skip the confirmation prompt

Details

---

mdm completion

Generate a shell completion script.

mdm completion [bash|zsh|fish|powershell]
mdm completion install     # write completion into your shell rc file

---

Files and locations

mdm keeps project state in the repository and per-user state under your home directory. Nothing is written outside these paths.

Path	Scope	Holds
mdm.lock	project	Installed skills, agent definitions, knowledge bundles, plugins, the configured harness list, and the scope's install mode. Commit it.
.agents/skills/, .agents/agents/, .agents/plugins/	project	The canonical copies mdm installs; each harness's own directory links to or copies from here. Usually gitignored.
$XDG_STATE_HOME/mdm/state.json	global	The per-user equivalent of mdm.lock.
~/.agents/mdm-state.json	global	The same file when XDG_STATE_HOME is unset (the default).

INSTALL_DIR (used by the install scripts) chooses where the mdm binary lands; see Installation.