Metadata-Version: 2.4
Name: apm-cli
Version: 0.7.7
Summary: MCP configuration tool
Author-email: Daniel Meppiel <user@example.com>
License: MIT License
        
        Copyright (c) Microsoft Corporation.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS
Requires-Dist: click>=8.0.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: python-frontmatter>=1.0.0
Requires-Dist: llm>=0.17.0
Requires-Dist: llm-github-models>=0.1.0
Requires-Dist: tomli>=1.2.0; python_version < "3.11"
Requires-Dist: toml>=0.10.2
Requires-Dist: rich>=13.0.0
Requires-Dist: rich-click>=1.7.0
Requires-Dist: watchdog>=3.0.0
Requires-Dist: GitPython>=3.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0.0; extra == "build"
Dynamic: license-file

# APM – Agent Package Manager

[![PyPI version](https://badge.fury.io/py/apm-cli.svg)](https://badge.fury.io/py/apm-cli)
[![CI/CD Pipeline](https://github.com/microsoft/apm/actions/workflows/build-release.yml/badge.svg)](https://github.com/microsoft/apm/actions/workflows/build-release.yml)
[![Downloads](https://img.shields.io/pypi/dm/apm-cli.svg)](https://pypi.org/project/apm-cli/)
[![GitHub stars](https://img.shields.io/github/stars/microsoft/apm.svg?style=social&label=Star)](https://github.com/microsoft/apm/stargazers)

**An open-source, community-driven dependency manager for AI agents.** `apm.yml` declares the skills, prompts, instructions, and tools your project needs — so every developer gets the same agent setup. Packages can depend on packages, and APM resolves the full tree.

Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent configuration.

GitHub Copilot · Cursor · Claude · Codex · Gemini

## Why APM

AI coding agents need context to be useful: what standards to follow, what prompts to use, what skills to leverage. Today this is manual — each developer installs things one by one, writes instructions from scratch, copies files around. None of it is portable. There's no manifest for it.

**APM fixes this.** You declare your project's agentic dependencies once, and every developer who clones your repo gets a fully configured agent setup in seconds. Packages can depend on other packages — APM resolves transitive dependencies automatically, just like npm or pip.

## See It in Action

```yaml
# apm.yml — ships with your project, like package.json
name: your project
version: 1.0.0
dependencies:
  apm:
    # Skills from any repository
    - anthropics/skills/skills/frontend-design
    - microsoft/GitHub-Copilot-for-Azure/plugin/skills/azure-compliance
    # A full APM package with rules, skills, prompts, hooks...
    - microsoft/apm-sample-package
    # Specific agent primitives from any repository
    - github/awesome-copilot/skills/review-and-refactor
    - github/awesome-copilot/agents/api-architect.agent.md
    # Plugins (auto-detected from plugin.json)
    - github/awesome-copilot/plugins/context-engineering
```

New developer joins the team:

```bash
git clone <org/repo>
cd <repo>
apm install
```

**That's it.** Copilot, Claude, Cursor — every agent is configured with the right skills, prompts, and coding standards.

→ [View the full example project](https://github.com/microsoft/apm-sample-package)

## Not Just Skills

Skill registries install skills. APM manages **every primitive** your AI agents need:

| Primitive | What it does | Example |
|-----------|-------------|---------|
| **Instructions** | Coding standards, guardrails | "Use type hints in all Python files" |
| **Skills** | AI capabilities, workflows | Form builder, code reviewer |
| **Prompts** | Reusable slash commands | `/security-audit`, `/design-review` |
| **Agents** | Specialized personas | Accessibility auditor, API designer |
| **Hooks** | Lifecycle event handlers | Pre-tool validation, post-tool linting |
| **Plugins** | Pre-packaged agent bundles | Context engineering, commit helpers |
| **MCP Servers** | Tool integrations | Database access, API connectors |

All declared in one manifest. All installed with one command — including transitive dependencies:

**`apm install`** → installs prompts, agents, skills, and instructions under `.github/instructions/` when editor integration (e.g., VS Code) is enabled
**`apm compile`** → compiles instructions into `AGENTS.md` (Copilot, Cursor, Codex) and `CLAUDE.md` (Claude)

## Get Started

**1. Install APM**

```bash
curl -sSL https://raw.githubusercontent.com/microsoft/apm/main/install.sh | sh
```

<details>
<summary>Homebrew or pip</summary>

```bash
brew install microsoft/apm/apm
# or
pip install apm-cli
```
</details>

**2. Add APM packages to your project**

```bash
apm install microsoft/apm-sample-package
apm install anthropics/skills/skills/frontend-design
apm install github/awesome-copilot/agents/api-architect.agent.md
apm install github/awesome-copilot/plugins/context-engineering
```

**Done.** Open your project in VS Code or Claude and your AI tools are ready.

## Install From Anywhere

```bash
# GitHub (shorthand)
apm install owner/repo
apm install owner/repo/path
# GitLab / Bitbucket / any git host
apm install https://gitlab.com/acme/coding-standards.git
apm install git@bitbucket.org:team/security-rules.git
apm install gitlab.com/acme/repo
# GitHub Enterprise Server
apm install ghe.company.com/owner/repo
# Azure DevOps
apm install dev.azure.com/org/project/repo
```

## Create & Share Packages

```bash
apm init my-standards && cd my-standards
```

```
my-standards/
├── apm.yml              # Package manifest
└── .apm/
    ├── instructions/    # Guardrails (.instructions.md)
    ├── prompts/         # Slash commands (.prompt.md)
    ├── skills/          # Agent Skills (SKILL.md)
    ├── agents/          # Personas (.agent.md)
    └── hooks/           # Event handlers (.json)
```

Add a guardrail and publish:

```bash
cat > .apm/instructions/python.instructions.md << 'EOF'
---
applyTo: "**/*.py"
---
# Python Standards
- Use type hints for all functions
- Follow PEP 8 style guidelines
EOF

git add . && git commit -m "Initial standards" && git push
```

Anyone can now `apm install you/my-standards`.

## Key Commands

| Command | What it does |
|---------|--------------|
| `apm install <pkg>` | Add a package and integrate its primitives |
| `apm compile` | Compile instructions into AGENTS.md / CLAUDE.md |
| `apm init [name]` | Scaffold a new APM project or package |
| `apm run <prompt>` | Execute a prompt workflow via AI runtime |
| `apm uninstall <pkg>` | Remove a package from apm.yml and clean up its files |
| `apm pack` | Bundle resolved dependencies for offline distribution |
| `apm deps list` | Show installed packages and versions |

→ [Full CLI Reference](docs/cli-reference.md)

## Configuration

For private repos or Azure DevOps, set a token. For other hosts (GitLab, Bitbucket, etc.), configure SSH keys or use `git credential-manager`:

| Token | When you need it |
|-------|-----------------|
| `GITHUB_APM_PAT` | Private GitHub packages |
| `ADO_APM_PAT` | Azure DevOps packages |
| `GITHUB_COPILOT_PAT` | Running prompts via `apm run` |

→ [Complete setup guide](docs/getting-started.md)

---

## APM Packages

An APM package is anything you can point `apm install` at: a full package with an `apm.yml` manifest and `.apm/` folder, a plugin with `plugin.json`, a single primitive file (`.instructions.md`, `.prompt.md`, `.agent.md`), a skill folder, or any subtree inside a repository. Hooks are auto-discovered when a package contains them. See [Primitives](docs/primitives.md) for details on each type.

APM installs from **any git host** — GitHub, GitLab, Bitbucket, self-hosted servers, GitHub Enterprise, and Azure DevOps. Use HTTPS or SSH git URLs, or the `owner/repo` shorthand for GitHub. See [Package Sources](docs/getting-started.md#package-sources) for host configuration.

Popular sources to get you started:

| Package | What you get |
|---------|-------------|
| [github/awesome-copilot](https://github.com/github/awesome-copilot) | Community prompts, agents & instructions for GitHub Copilot |
| [anthropics/skills](https://github.com/anthropics/skills) | Anthropic's official agent skills |
| [microsoft/GitHub-Copilot-for-Azure](https://github.com/microsoft/GitHub-Copilot-for-Azure/tree/main/plugin/skills) | Azure Skills |

---

## Roadmap

See the [APM Roadmap](https://github.com/microsoft/apm/discussions/116) for what's coming next.

## Documentation

| | |
|---|---|
| **Get Started** | [Quick Start](docs/getting-started.md) · [Core Concepts](docs/concepts.md) · [Examples](docs/examples.md) |
| **Reference** | [CLI Reference](docs/cli-reference.md) · [Compilation Engine](docs/compilation.md) · [Skills](docs/skills.md) · [Plugins](docs/plugins.md) · [Integrations](docs/integrations.md) |
| **Advanced** | [Dependencies](docs/dependencies.md) · [Primitives](docs/primitives.md) · [Contributing](CONTRIBUTING.md) |

---

**Built on open standards:** [AGENTS.md](https://agents.md) · [Agent Skills](https://agentskills.io) · [MCP](https://modelcontextprotocol.io)

**Learn AI-Native Development** → [Awesome AI Native](https://danielmeppiel.github.io/awesome-ai-native)
A practical learning path for AI-Native Development, leveraging APM along the way.

## Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
