CLI Commands

Complete reference for all APM CLI commands and options.

New to APM?

See Installation and Quick Start to get up and running.

Global Options

apm [OPTIONS] COMMAND [ARGS]...

Options

• --version - Show version and exit
• --help - Show help message and exit

Core Commands

apm init - Initialize new APM project

Initialize a new APM project with minimal apm.yml configuration (like npm init).

apm init [PROJECT_NAME] [OPTIONS]

Arguments:

• PROJECT_NAME - Optional name for new project directory. Use . to explicitly initialize in current directory

Options:

• -y, --yes - Skip interactive prompts and use auto-detected defaults
• --plugin - Initialize as a plugin authoring project (creates plugin.json + apm.yml with devDependencies)

Examples:

# Initialize in current directory (interactive)
apm init

# Initialize in current directory with defaults
apm init --yes

# Create new project directory
apm init my-hello-world

# Create project with auto-detected defaults
apm init my-project --yes

# Initialize a plugin authoring project
apm init my-plugin --plugin

Behavior:

• Minimal by default: Creates only apm.yml with auto-detected metadata
• Interactive mode: Prompts for project details unless --yes specified
• Auto-detection: Automatically detects author from git config user.name and description from project context
• Brownfield friendly: Works cleanly in existing projects without file pollution
• Plugin mode (--plugin): Creates both plugin.json and apm.yml with an empty devDependencies section. Plugin names must be kebab-case (^[a-z][a-z0-9-]{0,63}$), max 64 characters

Creates:

• apm.yml - Minimal project configuration with empty dependencies and scripts sections
• plugin.json - Plugin manifest (only with --plugin)

Auto-detected fields:

• name - From project directory name
• author - From git config user.name (fallback: “Developer”)
• description - Generated from project name
• version - Defaults to “1.0.0”

apm install - Install APM and MCP dependencies

Install APM package and MCP server dependencies from apm.yml (like npm install). Auto-creates minimal apm.yml when packages are specified but no manifest exists.

apm install [PACKAGES...] [OPTIONS]

Arguments:

• PACKAGES - Optional APM packages to add and install. Accepts shorthand (owner/repo), HTTPS URLs, SSH URLs, FQDN shorthand (host/owner/repo), local filesystem paths (./path, ../path, /absolute/path, ~/path), or marketplace references (NAME@MARKETPLACE). All forms are normalized to canonical format in apm.yml.

Options:

• --runtime TEXT - Target specific runtime only (copilot, codex, vscode)
• --exclude TEXT - Exclude specific runtime from installation
• --only [apm|mcp] - Install only specific dependency type
• --target [copilot|claude|cursor|codex|opencode|all] - Force deployment to a specific target (overrides auto-detection)
• --update - Update dependencies to latest Git references
• --force - Overwrite locally-authored files on collision; bypass security scan blocks
• --dry-run - Show what would be installed without installing
• --parallel-downloads INTEGER - Max concurrent package downloads (default: 4, 0 to disable)
• --verbose - Show individual file paths and full error details in the diagnostic summary
• --trust-transitive-mcp - Trust self-defined MCP servers from transitive packages (skip re-declaration requirement)
• --dev - Add packages to devDependencies instead of dependencies. Dev deps are installed locally but excluded from apm pack --format plugin bundles
• -g, --global - Install to user scope (~/.apm/) instead of the current project. Primitives deploy to ~/.copilot/, ~/.claude/, etc.

Behavior:

• apm install (no args): Installs all packages from apm.yml
• apm install <package>: Installs only the specified package (adds to apm.yml if not present)

Diff-Aware Installation (manifest as source of truth):

• MCP servers already configured with matching config are skipped (already configured)
• MCP servers already configured but with changed manifest config are re-applied automatically (updated)
• APM packages removed from apm.yml have their deployed files cleaned up on the next full apm install
• APM packages whose ref/version changed in apm.yml are re-downloaded automatically (no --update needed)
• --force remains available for full overwrite/reset scenarios

Examples:

# Install all dependencies from apm.yml
apm install

# Install ONLY this package (not others in apm.yml)
apm install microsoft/apm-sample-package

# Install via HTTPS URL (normalized to owner/repo in apm.yml)
apm install https://github.com/microsoft/apm-sample-package.git

# Install from a non-GitHub host (FQDN preserved)
apm install https://gitlab.com/acme/coding-standards.git

# Add multiple packages and install
apm install org/pkg1 org/pkg2

# Install a Claude Skill from a subdirectory
apm install ComposioHQ/awesome-claude-skills/brand-guidelines

# Install only APM dependencies (skip MCP servers)
apm install --only=apm

# Install only MCP dependencies (skip APM packages)
apm install --only=mcp

# Preview what would be installed
apm install --dry-run

# Update existing dependencies to latest versions
apm install --update

# Install for all runtimes except Codex
apm install --exclude codex

# Trust self-defined MCP servers from transitive packages
apm install --trust-transitive-mcp

# Install as a dev dependency (excluded from plugin bundles)
apm install --dev owner/test-helpers

# Install from a local path (copies to apm_modules/_local/)
apm install ./packages/my-shared-skills
apm install /home/user/repos/my-ai-package

# Install to user scope (available across all projects)
apm install -g microsoft/apm-sample-package

# Install a plugin from a registered marketplace
apm install code-review@acme-plugins

Auto-Bootstrap Behavior:

• With packages + no apm.yml: Automatically creates minimal apm.yml, adds packages, and installs
• Without packages + no apm.yml: Shows helpful error suggesting apm init or apm install <org/repo>
• With apm.yml: Works as before - installs existing dependencies or adds new packages

Dependency Types:

• APM Dependencies: Git repositories containing apm.yml (GitHub, GitLab, Bitbucket, or any git host)
• Claude Skills: Repositories with SKILL.md (auto-generates apm.yml upon installation)
  • Example: apm install ComposioHQ/awesome-claude-skills/brand-guidelines
  • Skills are transformed to .github/agents/*.agent.md for VSCode target
• Hook Packages: Repositories with hooks/*.json (no apm.yml or SKILL.md required)
  • Example: apm install anthropics/claude-plugins-official/plugins/hookify
• Virtual Packages: Single files or collections installed directly from URLs
  • Single .prompt.md or .agent.md files from any GitHub repository
  • Collections from curated sources (e.g., github/awesome-copilot)
  • Example: apm install github/awesome-copilot/skills/review-and-refactor
• MCP Dependencies: Model Context Protocol servers for runtime integration

Working Example with Dependencies:

# Example apm.yml with APM dependencies
name: my-compliance-project
version: 1.0.0
dependencies:
  apm:
    - microsoft/apm-sample-package  # Design standards, prompts
    - github/awesome-copilot/skills/review-and-refactor  # Code review skill
  mcp:
    - io.github.github/github-mcp-server

# Install all dependencies (APM + MCP)
apm install

# Install only APM dependencies for faster setup
apm install --only=apm

# Preview what would be installed
apm install --dry-run

Auto-Detection:

APM automatically detects which integrations to enable based on your project structure:

• VSCode integration: Enabled when .github/ directory exists
• Claude integration: Enabled when .claude/ directory exists
• Cursor integration: Enabled when .cursor/ directory exists
• OpenCode integration: Enabled when .opencode/ directory exists
• All integrations can coexist in the same project

VSCode Integration (.github/ present):

When you run apm install, APM automatically integrates primitives from installed packages:

• Prompts: .prompt.md files → .github/prompts/*.prompt.md
• Agents: .agent.md files → .github/agents/*.agent.md
• Chatmodes: .chatmode.md files → .github/agents/*.agent.md (renamed to modern format)
• Instructions: .instructions.md files → .github/instructions/*.instructions.md
• Control: Disable with apm config set auto-integrate false
• Smart updates: Only updates when package version/commit changes
• Hooks: Hook .json files → .github/hooks/*.json with scripts bundled
• Collision detection: Skips local files that aren’t managed by APM; use --force to overwrite
• Security scanning: Source files are scanned for hidden Unicode characters before deployment. Critical findings (tag characters, bidi overrides) block deployment; use --force to override. Exits with code 1 if any package was blocked.

Diagnostic Summary:

After installation completes, APM prints a grouped diagnostic summary instead of inline warnings. Categories include collisions (skipped files), cross-package skill replacements, warnings, and errors.

• Normal mode: Shows counts and actionable tips (e.g., “9 files skipped — use apm install --force to overwrite”)
• Verbose mode (--verbose): Additionally lists individual file paths grouped by package, and full error details

# See exactly which files were skipped or had issues
apm install --verbose

Claude Integration (.claude/ present):

APM also integrates with Claude Code when .claude/ directory exists:

• Agents: .agent.md and .chatmode.md files → .claude/agents/*.md
• Commands: .prompt.md files → .claude/commands/*.md
• Hooks: Hook definitions merged into .claude/settings.json hooks key

Skill Integration:

Skills are copied directly to target directories:

• Primary: .github/skills/{skill-name}/ — Entire skill folder copied
• Compatibility: .claude/skills/{skill-name}/ — Also copied if .claude/ folder exists

Example Integration Output:

✓ microsoft/apm-sample-package
  ├─ 3 prompts integrated → .github/prompts/
  ├─ 1 instruction(s) integrated → .github/instructions/
  ├─ 1 agents integrated → .claude/agents/
  └─ 3 commands integrated → .claude/commands/

This makes all package primitives available in VSCode, Cursor, OpenCode, Claude Code, and compatible editors for immediate use with your coding agents.

apm uninstall - Remove APM packages

Remove installed APM packages and their integrated files.

apm uninstall [OPTIONS] PACKAGES...

Arguments:

• PACKAGES... - One or more packages to uninstall. Accepts any format — shorthand (owner/repo), HTTPS URL, SSH URL, or FQDN. APM resolves each to the canonical identity stored in apm.yml.

Options:

• --dry-run - Show what would be removed without removing
• -g, --global - Remove from user scope (~/.apm/) instead of the current project

Examples:

# Uninstall a package
apm uninstall microsoft/apm-sample-package

# Uninstall using an HTTPS URL (resolves to same identity)
apm uninstall https://github.com/microsoft/apm-sample-package.git

# Preview what would be removed
apm uninstall microsoft/apm-sample-package --dry-run

# Uninstall from user scope
apm uninstall -g microsoft/apm-sample-package

What Gets Removed:

Item	Location
Package entry	apm.yml dependencies section
Package folder	apm_modules/owner/repo/
Transitive deps	apm_modules/ (orphaned transitive dependencies)
Integrated prompts	.github/prompts/*.prompt.md
Integrated agents	.github/agents/*.agent.md
Integrated chatmodes	.github/agents/*.agent.md
Claude commands	.claude/commands/*.md
Skill folders	.github/skills/{folder-name}/
Integrated hooks	.github/hooks/*.json
Claude hook settings	.claude/settings.json (hooks key cleaned)
Cursor rules	.cursor/rules/*.mdc
Cursor agents	.cursor/agents/*.md
Cursor skills	.cursor/skills/{folder-name}/
Cursor hooks	.cursor/hooks.json (hooks key cleaned)
OpenCode agents	.opencode/agents/*.md
OpenCode commands	.opencode/commands/*.md
OpenCode skills	.opencode/skills/{folder-name}/
Lockfile entries	apm.lock.yaml (removed packages + orphaned transitives)

Behavior:

• Removes package from apm.yml dependencies
• Deletes package folder from apm_modules/
• Removes orphaned transitive dependencies (npm-style pruning via apm.lock.yaml)
• Removes all deployed integration files tracked in apm.lock.yaml deployed_files
• Updates apm.lock.yaml (or deletes it if no dependencies remain)
• Cleans up empty parent directories
• Safe operation: only removes files tracked in the deployed_files manifest

apm prune - Remove orphaned packages

Remove APM packages from apm_modules/ that are not listed in apm.yml, along with their deployed integration files (prompts, agents, hooks, etc.).

apm prune [OPTIONS]

Options:

• --dry-run - Show what would be removed without removing

Examples:

# Remove orphaned packages and their deployed files
apm prune

# Preview what would be removed
apm prune --dry-run

Behavior:

• Removes orphaned package directories from apm_modules/
• Removes deployed integration files (prompts, agents, hooks, etc.) for pruned packages using the deployed_files manifest in apm.lock.yaml
• Updates apm.lock.yaml to reflect the pruned state

apm audit - Scan for hidden Unicode characters

Scan installed packages or arbitrary files for hidden Unicode characters that could embed invisible instructions in prompt files.

apm audit [PACKAGE] [OPTIONS]

Arguments:

• PACKAGE - Optional package key to scan (repo URL from lockfile). If omitted, scans all installed packages.

Options:

• --file PATH - Scan an arbitrary file instead of installed packages
• --strip - Remove dangerous characters (critical + warning severity) while preserving info-level content like emoji. ZWJ inside emoji sequences is preserved.
• --dry-run - Preview what --strip would remove without modifying files
• -v, --verbose - Show info-level findings and file details
• -f, --format [text|json|sarif|markdown] - Output format: text (default), json (machine-readable), sarif (GitHub Code Scanning), markdown (step summaries). Cannot be combined with --strip or --dry-run.
• -o, --output PATH - Write report to file. Auto-detects format from extension (.sarif, .sarif.json → SARIF; .json → JSON; .md → Markdown) when --format is not specified.
• --ci - Run lockfile consistency checks for CI/CD gates. Exit 0 if clean, 1 if violations found.
• --policy SOURCE - (Experimental) Policy source: org (auto-discover from org), file path, or URL. Used with --ci to run policy checks on top of baseline.
• --no-cache - Force fresh policy fetch (skip cache). Only relevant with --policy.
• --no-fail-fast - Run all checks even after a failure. By default, CI mode stops at the first failing check to save time.

Examples:

# Scan all installed packages
apm audit

# Scan a specific package
apm audit https://github.com/owner/repo

# Scan any file (even non-APM-managed)
apm audit --file .cursorrules

# Remove dangerous characters (preserves emoji)
apm audit --strip

# Preview what --strip would remove
apm audit --strip --dry-run

# Verbose output with info-level findings
apm audit --verbose

# SARIF output to stdout (for CI pipelines)
apm audit -f sarif

# Markdown output (for GitHub step summaries)
apm audit -f markdown

# Write SARIF report to file
apm audit -o report.sarif

# JSON report to file
apm audit -f json -o results.json

# CI lockfile consistency gate
apm audit --ci

# CI gate with org policy checks
apm audit --ci --policy org

# CI gate with local policy file
apm audit --ci --policy ./apm-policy.yml

# Force fresh policy fetch
apm audit --ci --policy org --no-cache

# Run all checks (no fail-fast) for full diagnostic report
apm audit --ci --policy org --no-fail-fast

Exit codes (content scanning mode):

Code	Meaning
0	Clean — no findings, info-only, or successful strip
1	Critical findings — tag characters, bidi overrides, or variation selectors 17–256
2	Warnings only — zero-width characters, bidi marks, or other suspicious content

Exit codes (--ci mode):

Code	Meaning
0	All checks passed
1	One or more checks failed

What it detects:

• Critical: Tag characters (U+E0001–E007F), bidi overrides (U+202A–E, U+2066–9), variation selectors 17–256 (U+E0100–E01EF, Glassworm attack vector)
• Warning: Zero-width spaces/joiners (U+200B–D), variation selectors 1–15 (U+FE00–FE0E), bidi marks (U+200E–F, U+061C), invisible operators (U+2061–4), annotation markers (U+FFF9–B), deprecated formatting (U+206A–F), soft hyphen (U+00AD), mid-file BOM
• Info: Non-breaking spaces, unusual whitespace, emoji presentation selector (U+FE0F). ZWJ between emoji characters is context-downgraded to info.

apm pack - Create a portable bundle

Create a self-contained bundle from installed APM dependencies using the deployed_files recorded in apm.lock.yaml as the source of truth.

apm pack [OPTIONS]

Options:

• -o, --output PATH - Output directory (default: ./build)
• -t, --target [copilot|vscode|claude|cursor|codex|opencode|all] - Filter files by target. Auto-detects from apm.yml if not specified. vscode is an alias for copilot
• --archive - Produce a .tar.gz archive instead of a directory
• --dry-run - List files that would be packed without writing anything
• --format [apm|plugin] - Bundle format (default: apm). plugin produces a standalone plugin directory with plugin.json
• --force - On collision (plugin format), last writer wins instead of first

Examples:

# Pack to ./build/<name>-<version>/
apm pack

# Pack as a .tar.gz archive
apm pack --archive

# Pack only VS Code / Copilot files
apm pack --target vscode

# Export as a standalone plugin directory
apm pack --format plugin

# Preview what would be packed
apm pack --dry-run

# Custom output directory
apm pack -o dist/

Behavior:

• Reads apm.lock.yaml to enumerate all deployed_files from installed dependencies
• Scans files for hidden Unicode characters before bundling — warns if findings are detected (non-blocking; consumers are protected by apm install/apm unpack which block on critical)
• Copies files preserving directory structure
• Writes an enriched apm.lock.yaml inside the bundle with a pack: metadata section (the project’s own apm.lock.yaml is never modified)
• Plugin format (--format plugin): Remaps .apm/ content into plugin-native paths (agents/, skills/, commands/, etc.), generates or updates plugin.json, merges hooks into a single hooks.json. devDependencies are also excluded from plugin bundles. See Pack & Distribute for the full mapping table

Target filtering:

Target	Includes paths starting with
vscode	.github/
claude	.claude/
cursor	.cursor/
opencode	.opencode/
all	all of the above

Enriched lockfile example:

pack:
  format: apm
  target: vscode
  packed_at: '2026-03-09T12:00:00+00:00'
lockfile_version: '1'
generated_at: ...
dependencies:
  - repo_url: owner/repo
    ...

apm unpack - Extract a bundle

Extract an APM bundle into the current project with optional completeness verification.

apm unpack BUNDLE_PATH [OPTIONS]

Arguments:

• BUNDLE_PATH - Path to a .tar.gz archive or an unpacked bundle directory

Options:

• -o, --output PATH - Target project directory (default: current directory)
• --skip-verify - Skip completeness verification against the bundle lockfile
• --force - Deploy despite critical hidden-character findings
• --dry-run - Show what would be extracted without writing anything

Examples:

# Unpack an archive into the current directory
apm unpack ./build/my-pkg-1.0.0.tar.gz

# Unpack into a specific directory
apm unpack bundle.tar.gz --output /path/to/project

# Skip verification (useful for partial bundles)
apm unpack bundle.tar.gz --skip-verify

# Preview what would be extracted
apm unpack bundle.tar.gz --dry-run

# Deploy despite critical hidden-character findings
apm unpack bundle.tar.gz --force

Behavior:

• Additive-only: only writes files listed in the bundle’s apm.lock.yaml; never deletes existing files
• If a local file has the same path as a bundle file, the bundle file wins (overwrite)
• Security scanning: Bundle contents are scanned before deployment. Critical findings block deployment unless --force is used (exit code 1)
• Verification checks that all deployed_files from the bundle lockfile are present in the bundle
• The bundle’s apm.lock.yaml is metadata only — it is not copied to the output directory

apm update - Update APM to the latest version

Update the APM CLI to the latest version available on GitHub releases.

apm update [OPTIONS]

Options:

• --check - Only check for updates without installing

Examples:

# Check if an update is available
apm update --check

# Update to the latest version
apm update

Behavior:

• Fetches latest release from GitHub
• Compares with current installed version
• Downloads and runs the official platform installer (install.sh on macOS/Linux, install.ps1 on Windows)
• Preserves existing configuration and projects
• Shows progress and success/failure status

Version Checking: APM automatically checks for updates (at most once per day) when running any command. If a newer version is available, you’ll see a yellow warning:

⚠️  A new version of APM is available: 0.7.0 (current: 0.6.3)
Run apm update to upgrade

This check is non-blocking and cached to avoid slowing down the CLI.

Manual Update: If the automatic update fails, you can always update manually:

Linux / macOS

curl -sSL https://aka.ms/apm-unix | sh

Windows

powershell -ExecutionPolicy Bypass -c "irm https://aka.ms/apm-windows | iex"

apm deps - Manage APM package dependencies

Manage APM package dependencies with installation status, tree visualization, and package information.

apm deps COMMAND [OPTIONS]

apm deps list - List installed APM dependencies

Show all installed APM dependencies in a Rich table format with per-primitive counts.

apm deps list [OPTIONS]

Options:

• -g, --global - List user-scope packages from ~/.apm/ instead of the current project
• --all - List packages from both project and user scope

Examples:

# Show project-scope packages
apm deps list

# Show user-scope packages
apm deps list -g

# Show both scopes
apm deps list --all

Sample Output:

┌─────────────────────┬─────────┬──────────┬─────────┬──────────────┬────────┬────────┐
│ Package             │ Version │ Source   │ Prompts │ Instructions │ Agents │ Skills │
├─────────────────────┼─────────┼──────────┼─────────┼──────────────┼────────┼────────┤
│ compliance-rules    │ 1.0.0   │ github   │    2    │      1       │   -    │   1    │
│ design-guidelines   │ 1.0.0   │ github   │    -    │      1       │   1    │   -    │
└─────────────────────┴─────────┴──────────┴─────────┴──────────────┴────────┴────────┘

Output includes:

• Package name and version
• Source information
• Per-primitive counts (prompts, instructions, agents, skills)

apm deps tree - Show dependency tree structure

Display dependencies in hierarchical tree format with primitive counts.

apm deps tree

Examples:

# Show dependency tree
apm deps tree

Sample Output:

company-website (local)
├── compliance-rules@1.0.0
│   ├── 1 instructions
│   ├── 1 chatmodes
│   └── 3 agent workflows
└── design-guidelines@1.0.0
    ├── 1 instructions
    └── 3 agent workflows

Output format:

• Hierarchical tree showing project name and dependencies
• File counts grouped by type (instructions, chatmodes, agent workflows)
• Version numbers from dependency package metadata
• Version information for each dependency

apm deps info - Show detailed package information

Display comprehensive information about a specific installed package.

apm deps info PACKAGE_NAME

Arguments:

• PACKAGE_NAME - Name of the package to show information about

Examples:

# Show details for compliance rules package
apm deps info compliance-rules

# Show info for design guidelines package
apm deps info design-guidelines

Output includes:

• Complete package metadata (name, version, description, author)
• Source repository and installation details
• Detailed context file counts by type
• Agent workflow descriptions and counts
• Installation path and status

apm deps clean - Remove all APM dependencies

Remove the entire apm_modules/ directory and all installed APM packages.

apm deps clean [OPTIONS]

Options:

• --dry-run - Show what would be removed without removing
• --yes, -y - Skip confirmation prompt (for non-interactive/scripted use)

Examples:

# Remove all APM dependencies (with confirmation)
apm deps clean

# Preview what would be removed
apm deps clean --dry-run

# Remove without confirmation (e.g. in CI pipelines)
apm deps clean --yes

Behavior:

• Shows confirmation prompt before deletion (unless --yes is provided)
• Removes entire apm_modules/ directory
• Displays count of packages that will be removed
• Can be cancelled with Ctrl+C or ‘n’ response

apm deps update - Update APM dependencies

Re-resolve git references to their latest commits, download updated content, re-integrate primitives, and regenerate the lockfile.

apm deps update [PACKAGES...] [OPTIONS]

Arguments:

• PACKAGES - Optional. One or more packages to update. Omit to update all.

Options:

• --verbose, -v - Show detailed update information
• --force - Overwrite locally-authored files on collision
• --target, -t - Force deployment to a specific target (copilot, claude, cursor, opencode, vscode, agents, all)
• --parallel-downloads - Max concurrent downloads (default: 4)

Examples:

# Update all APM dependencies to latest refs
apm deps update

# Update a specific package (short name or full owner/repo)
apm deps update owner/compliance-rules

# Update multiple packages
apm deps update org/pkg-a org/pkg-b

# Update with verbose output
apm deps update --verbose

# Force overwrite local files on collision
apm deps update --force

apm mcp - Browse MCP server registry

Browse and discover MCP servers from the GitHub MCP Registry.

apm mcp COMMAND [OPTIONS]

apm mcp list - List MCP servers

List all available MCP servers from the registry.

apm mcp list [OPTIONS]

Options:

• --limit INTEGER - Number of results to show (default: 20)

Examples:

# List available MCP servers
apm mcp list

# Limit results
apm mcp list --limit 20

apm mcp search - Search MCP servers

Search for MCP servers in the GitHub MCP Registry.

apm mcp search QUERY [OPTIONS]

Arguments:

• QUERY - Search term to find MCP servers

Options:

• --limit INTEGER - Number of results to show (default: 10)

Examples:

# Search for filesystem-related servers
apm mcp search filesystem

# Search with custom limit
apm mcp search database --limit 5

# Search for GitHub integration
apm mcp search github

apm mcp show - Show MCP server details

Show detailed information about a specific MCP server from the registry.

apm mcp show SERVER_NAME

Arguments:

• SERVER_NAME - Name or ID of the MCP server to show

Examples:

# Show details for a server by name
apm mcp show @modelcontextprotocol/servers/src/filesystem

# Show details by server ID
apm mcp show a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1

Output includes:

• Server name and description
• Latest version information
• Repository URL
• Available installation packages
• Installation instructions

apm marketplace - Plugin marketplace management

Register, browse, and manage plugin marketplaces. Marketplaces are GitHub repositories containing a marketplace.json index of plugins.

See the Marketplaces guide for concepts and workflows.

apm marketplace COMMAND [OPTIONS]

apm marketplace add - Register a marketplace

Register a GitHub repository as a plugin marketplace.

apm marketplace add OWNER/REPO [OPTIONS]

Arguments:

• OWNER/REPO - GitHub repository containing marketplace.json

Options:

• -n, --name TEXT - Custom display name for the marketplace
• -b, --branch TEXT - Branch to track (default: main)
• -v, --verbose - Show detailed output

Examples:

# Register a marketplace
apm marketplace add acme/plugin-marketplace

# Register with a custom name and branch
apm marketplace add acme/plugin-marketplace --name acme-plugins --branch release

apm marketplace list - List registered marketplaces

List all registered marketplaces with their source repository and branch.

apm marketplace list [OPTIONS]

Options:

• -v, --verbose - Show detailed output

Examples:

apm marketplace list

apm marketplace browse - Browse marketplace plugins

List all plugins available in a registered marketplace.

apm marketplace browse NAME [OPTIONS]

Arguments:

• NAME - Name of the registered marketplace

Options:

• -v, --verbose - Show detailed output

Examples:

# Browse all plugins in a marketplace
apm marketplace browse acme-plugins

apm marketplace update - Refresh marketplace cache

Refresh the cached marketplace.json for one or all registered marketplaces.

apm marketplace update [NAME] [OPTIONS]

Arguments:

• NAME - Optional marketplace name. Omit to refresh all.

Options:

• -v, --verbose - Show detailed output

Examples:

# Refresh a specific marketplace
apm marketplace update acme-plugins

# Refresh all marketplaces
apm marketplace update

apm marketplace remove - Remove a registered marketplace

Unregister a marketplace. Plugins previously installed from it remain pinned in apm.lock.yaml.

apm marketplace remove NAME [OPTIONS]

Arguments:

• NAME - Name of the marketplace to remove

Options:

• -y, --yes - Skip confirmation prompt
• -v, --verbose - Show detailed output

Examples:

# Remove with confirmation prompt
apm marketplace remove acme-plugins

# Remove without confirmation
apm marketplace remove acme-plugins --yes

apm search - Search plugins in a marketplace

Search for plugins by name or description within a specific marketplace.

apm search QUERY@MARKETPLACE [OPTIONS]

Arguments:

• QUERY@MARKETPLACE - Search term scoped to a marketplace (e.g., security@skills)

Options:

• --limit INTEGER - Maximum results to return (default: 20)
• -v, --verbose - Show detailed output

Examples:

# Search for code review plugins in a marketplace
apm search "code review@skills"

# Limit results
apm search "linting@awesome-copilot" --limit 5

apm run (Experimental) - Execute prompts

Execute a script defined in your apm.yml with parameters and real-time output streaming.

See the Agent Workflows guide for usage details.

apm run [SCRIPT_NAME] [OPTIONS]

Arguments:

• SCRIPT_NAME - Name of script to run from apm.yml scripts section

Options:

• -p, --param TEXT - Parameter in format name=value (can be used multiple times)

Examples:

# Run start script (default script)
apm run start --param name="<YourGitHubHandle>"

# Run with different scripts
apm run start --param name="Alice"
apm run llm --param service=api
apm run debug --param service=api

# Run specific scripts with parameters
apm run llm --param service=api --param environment=prod

Return Codes:

• 0 - Success
• 1 - Execution failed or error occurred

apm preview - Preview compiled scripts

Show the processed prompt content with parameters substituted, without executing.

apm preview [SCRIPT_NAME] [OPTIONS]

Arguments:

• SCRIPT_NAME - Name of script to preview from apm.yml scripts section

Options:

• -p, --param TEXT - Parameter in format name=value

Examples:

# Preview start script
apm preview start --param name="<YourGitHubHandle>"

# Preview specific script with parameters
apm preview llm --param name="Alice"

apm list - List available scripts

Display all scripts defined in apm.yml.

apm list

Examples:

# List all prompts in project
apm list

Output format:

Available scripts:
  start: codex hello-world.prompt.md
  llm: llm hello-world.prompt.md -m github/gpt-4o-mini
  debug: RUST_LOG=debug codex hello-world.prompt.md

apm compile - Compile APM context into distributed AGENTS.md files

Compile APM context files (chatmodes, instructions, contexts) into distributed AGENTS.md files with conditional sections, markdown link resolution, and project setup auto-detection.

apm compile [OPTIONS]

Options:

• -o, --output TEXT - Output file path (for single-file mode)
• -t, --target [vscode|agents|claude|codex|opencode|all] - Target agent format. agents is an alias for vscode. Auto-detects if not specified.
• --chatmode TEXT - Chatmode to prepend to the AGENTS.md file
• --dry-run - Preview compilation without writing files (shows placement decisions)
• --no-links - Skip markdown link resolution
• --with-constitution/--no-constitution - Include Spec Kit memory/constitution.md verbatim at top inside a delimited block (default: --with-constitution). When disabled, any existing block is preserved but not regenerated.
• --watch - Auto-regenerate on changes (file system monitoring)
• --validate - Validate primitives without compiling
• --single-agents - Force single-file compilation (legacy mode)
• -v, --verbose - Show detailed source attribution and optimizer analysis
• --local-only - Ignore dependencies, compile only local primitives
• --clean - Remove orphaned AGENTS.md files that are no longer generated

Target Auto-Detection:

When --target is not specified, APM auto-detects based on existing project structure:

Condition	Target	Output
.github/ exists only	vscode	AGENTS.md + .github/
.claude/ exists only	claude	CLAUDE.md + .claude/
.codex/ exists	codex	AGENTS.md + .codex/ + .agents/
Both folders exist	all	All outputs
Neither folder exists	minimal	AGENTS.md only

You can also set a persistent target in apm.yml:

name: my-project
version: 1.0.0
target: vscode  # or claude, codex, opencode, or all

Target Formats (explicit):

Target	Output Files	Best For
vscode	AGENTS.md, .github/prompts/, .github/agents/, .github/skills/	GitHub Copilot, Cursor, Gemini
claude	CLAUDE.md, .claude/commands/, SKILL.md	Claude Code, Claude Desktop
codex	AGENTS.md, .agents/skills/, .codex/agents/, .codex/hooks.json	Codex CLI
opencode	AGENTS.md, .opencode/agents/, .opencode/commands/, .opencode/skills/	OpenCode
all	All of the above	Universal compatibility

Examples:

# Basic compilation with auto-detected context
apm compile

# Generate with specific chatmode
apm compile --chatmode architect

# Preview without writing file
apm compile --dry-run

# Custom output file
apm compile --output docs/AI-CONTEXT.md

# Validate context without generating output
apm compile --validate

# Watch for changes and auto-recompile (development mode)
apm compile --watch

# Watch mode with dry-run for testing
apm compile --watch --dry-run

# Target specific agent formats
apm compile --target vscode    # AGENTS.md + .github/ only
apm compile --target claude    # CLAUDE.md + .claude/ only
apm compile --target opencode  # AGENTS.md + .opencode/ only
apm compile --target all       # All formats (default)

# Compile injecting Spec Kit constitution (auto-detected)
apm compile --with-constitution

# Recompile WITHOUT updating the block but preserving previous injection
apm compile --no-constitution

Watch Mode:

• Monitors .apm/, .github/instructions/, .github/chatmodes/ directories
• Auto-recompiles when .md or apm.yml files change
• Includes 1-second debounce to prevent rapid recompilation
• Press Ctrl+C to stop watching
• Requires watchdog library (automatically installed)

Validation Mode:

• Checks primitive structure and frontmatter completeness
• Displays actionable suggestions for fixing validation errors
• Exits with error code 1 if validation fails
• No output file generation in validation-only mode

Content Scanning: Compiled output is scanned for hidden Unicode characters before writing to disk. Critical findings cause apm compile to exit with code 1 — defense-in-depth since source files are already scanned during apm install.

Configuration Integration: The compile command supports configuration via apm.yml:

compilation:
  output: "AGENTS.md"           # Default output file
  chatmode: "backend-engineer"  # Default chatmode to use
  resolve_links: true           # Enable markdown link resolution
  exclude:                      # Directory exclusion patterns (glob syntax)
    - "apm_modules/**"          # Exclude installed packages
    - "tmp/**"                  # Exclude temporary files
    - "coverage/**"             # Exclude test coverage
    - "**/test-fixtures/**"     # Exclude test fixtures at any depth

Directory Exclusion Patterns:

Use the exclude field to skip directories during compilation. This improves performance in large monorepos and prevents duplicate instruction discovery from source package development directories.

Pattern examples:

• tmp - Matches directory named “tmp” at any depth
• projects/packages/apm - Matches specific nested path
• **/node_modules - Matches “node_modules” at any depth
• coverage/** - Matches “coverage” and all subdirectories
• projects/**/apm/** - Complex nested matching with **

Default exclusions (always applied, matched on exact path components):

• node_modules, __pycache__, .git, dist, build, apm_modules
• Hidden directories (starting with .)

Command-line options always override apm.yml settings. Priority order:

1. Command-line flags (highest priority)
2. apm.yml compilation section
3. Built-in defaults (lowest priority)

Generated AGENTS.md structure:

• Header - Generation metadata and APM version
• (Optional) Spec Kit Constitution Block - Delimited block:
  • Markers: <!-- SPEC-KIT CONSTITUTION: BEGIN --> / <!-- SPEC-KIT CONSTITUTION: END -->
  • Second line includes hash: <sha256_12> for drift detection
  • Entire raw file content in between (Phase 0: no summarization)
• Pattern-based Sections - Content grouped by exact applyTo patterns from instruction context files (e.g., “Files matching **/*.py”)
• Footer - Regeneration instructions

The structure is entirely dictated by the instruction context found in .apm/ and .github/instructions/ directories. No predefined sections or project detection are applied.

Primitive Discovery:

• Chatmodes: .chatmode.md files in .apm/chatmodes/, .github/chatmodes/
• Instructions: .instructions.md files in .apm/instructions/, .github/instructions/
• Workflows: .prompt.md files in project and .github/prompts/

APM integrates seamlessly with Spec-kit for specification-driven development, automatically injecting Spec-kit constitution into the compiled context layer.

apm config - Configure APM CLI

Manage APM CLI configuration settings. Running apm config without subcommands displays the current configuration.

apm config [COMMAND]

apm config - Show current configuration (default behavior)

Display current APM CLI configuration and project settings.

apm config

What’s displayed:

• Project configuration from apm.yml (if in an APM project)
  • Project name, version, entrypoint
  • Number of MCP dependencies
  • Compilation settings (output, chatmode, resolve_links)
• Global configuration
  • APM CLI version
  • auto-integrate setting

Examples:

# Show current configuration
apm config

apm config get - Get a configuration value

Get a specific configuration value or display all configuration values.

apm config get [KEY]

Arguments:

• KEY (optional) - Configuration key to retrieve. Supported keys:
  • auto-integrate - Whether to automatically integrate .prompt.md files into AGENTS.md

If KEY is omitted, displays all configuration values.

Examples:

# Get auto-integrate setting
apm config get auto-integrate

# Show all configuration
apm config get

apm config set - Set a configuration value

Set a configuration value globally for APM CLI.

apm config set KEY VALUE

Arguments:

• KEY - Configuration key to set. Supported keys:
  • auto-integrate - Enable/disable automatic integration of .prompt.md files
• VALUE - Value to set. For boolean keys, use: true, false, yes, no, 1, 0

Configuration Keys:

auto-integrate - Control automatic prompt integration

• Type: Boolean
• Default: true
• Description: When enabled, APM automatically discovers and integrates .prompt.md files from .github/prompts/ and .apm/prompts/ directories into the compiled AGENTS.md file. This ensures all prompts are available to coding agents without manual compilation.
• Use Cases:
  • Set to false if you want to manually manage which prompts are compiled
  • Set to true to ensure all prompts are always included in the context

Examples:

# Enable auto-integration (default)
apm config set auto-integrate true

# Disable auto-integration
apm config set auto-integrate false

# Using alternative boolean values
apm config set auto-integrate yes
apm config set auto-integrate 1

Runtime Management (Experimental)

apm runtime (Experimental) - Manage AI runtimes

APM manages AI runtime installation and configuration automatically. Currently supports three runtimes: copilot, codex, and llm.

See the Agent Workflows guide for usage details.

apm runtime COMMAND [OPTIONS]

Supported Runtimes:

• copilot - GitHub Copilot coding agent
• codex - OpenAI Codex CLI with GitHub Models support
• llm - Simon Willison’s LLM library with multiple providers

apm runtime setup - Install AI runtime

Download and configure an AI runtime from official sources.

apm runtime setup [OPTIONS] {copilot|codex|llm}

Arguments:

• {copilot|codex|llm} - Runtime to install

Options:

• --version TEXT - Specific version to install
• --vanilla - Install runtime without APM configuration (uses runtime’s native defaults)

Examples:

# Install Codex with APM defaults
apm runtime setup codex

# Install LLM with APM defaults
apm runtime setup llm

Windows support:

• On Windows, APM runs the setup scripts through PowerShell automatically
• No special flags are required
• Platform detection is automatic

Default Behavior:

• Installs runtime binary from official sources
• Configures with GitHub Models (free) as APM default
• Creates configuration file at ~/.codex/config.toml or similar
• Provides clear logging about what’s being configured

Vanilla Behavior (--vanilla flag):

• Installs runtime binary only
• No APM-specific configuration applied
• Uses runtime’s native defaults (e.g., OpenAI for Codex)
• No configuration files created by APM

apm runtime list - Show installed runtimes

List all available runtimes and their installation status.

apm runtime list

Output includes:

• Runtime name and description
• Installation status (✅ Installed / ❌ Not installed)
• Installation path and version
• Configuration details

apm runtime remove - Uninstall runtime

Remove an installed runtime and its configuration.

apm runtime remove [OPTIONS] {copilot|codex|llm}

Arguments:

• {copilot|codex|llm} - Runtime to remove

Options:

• --yes - Confirm the action without prompting

apm runtime status - Show active runtime and preference order

Display which runtime APM will use for execution and runtime preference order.

apm runtime status

Output includes:

• Runtime preference order (copilot → codex → llm)
• Currently active runtime
• Next steps if no runtime is available