From b5f2c2c0ba91bd9cb7bf77856659d24b5f87431e Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Thu, 12 Mar 2026 13:59:42 +0100 Subject: [PATCH] docs: remove duplicated content from CLI reference page The CLI Commands reference page duplicated content from the Quick Start and Installation pages, and included non-reference material (tips, integration examples, file formats, project structure). Removed 179 lines and replaced with a brief intro linking to the canonical pages. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../content/docs/reference/cli-commands.md | 183 +----------------- 1 file changed, 4 insertions(+), 179 deletions(-) diff --git a/docs/src/content/docs/reference/cli-commands.md b/docs/src/content/docs/reference/cli-commands.md index 4038c80d5..081917f5a 100644 --- a/docs/src/content/docs/reference/cli-commands.md +++ b/docs/src/content/docs/reference/cli-commands.md @@ -4,53 +4,11 @@ sidebar: order: 1 --- -Complete command-line interface reference for Agent Package Manager (APM). +Complete reference for all APM CLI commands and options. -## Quick Start - -```bash -# 1. Set your GitHub tokens (minimal setup) -export GITHUB_APM_PAT=your_fine_grained_token_here -# Optional: export GITHUB_TOKEN=your_models_token # For Codex CLI with GitHub Models - -# 2. Install APM CLI (GitHub org members) -curl -sSL https://raw.githubusercontent.com/microsoft/apm/main/install.sh | sh - -# 3. Setup runtime -apm runtime setup copilot - -# 4. Create project -apm init my-project && cd my-project - -# 5. Run your first workflow -apm compile && apm run start --param name="" -``` - -## Installation - -### Quick Install (Recommended) -```bash -curl -sSL https://raw.githubusercontent.com/microsoft/apm/main/install.sh | sh -``` - -### Manual Download -Download from [GitHub Releases](https://github.com/microsoft/apm/releases/latest): -```bash -# Linux x86_64 -curl -L https://github.com/microsoft/apm/releases/latest/download/apm-linux-x86_64 -o apm && chmod +x apm - -# macOS Intel -curl -L https://github.com/microsoft/apm/releases/latest/download/apm-darwin-x86_64 -o apm && chmod +x apm - -# macOS Apple Silicon -curl -L https://github.com/microsoft/apm/releases/latest/download/apm-darwin-arm64 -o apm && chmod +x apm -``` - -### From Source (Developers) -```bash -git clone https://github.com/microsoft/apm.git -cd apm && pip install -e . -``` +:::tip[New to APM?] +See [Installation](../../getting-started/installation/) and [Quick Start](../../getting-started/quick-start/) to get up and running. +::: ## Global Options @@ -1108,136 +1066,3 @@ apm runtime status - Currently active runtime - Next steps if no runtime is available -## File Formats - -### APM Project Configuration (`apm.yml`) -```yaml -name: my-project -version: 1.0.0 -description: My APM application -author: Your Name -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" - -dependencies: - mcp: - - ghcr.io/github/github-mcp-server -``` - -### Prompt Format (`.prompt.md`) -```markdown ---- -description: Brief description of what this prompt does -mcp: - - ghcr.io/github/github-mcp-server -input: - - param1 - - param2 ---- - -# Prompt Title - -Your prompt content here with ${input:param1} substitution. -``` - -### Supported Prompt Locations -APM discovers `.prompt.md` files anywhere in your project: -- `./hello-world.prompt.md` -- `./prompts/my-prompt.prompt.md` -- `./.github/prompts/workflow.prompt.md` -- `./docs/prompts/helper.prompt.md` - -## Quick Start Workflow - -```bash -# 1. Initialize new project (like npm init) -apm init my-hello-world - -# 2. Navigate to project -cd my-hello-world - -# 3. Discover MCP servers (optional) -apm mcp search filesystem -apm mcp show @modelcontextprotocol/servers/src/filesystem - -# 4. Install dependencies (like npm install) -apm install - -# 5. Run the hello world prompt -apm run start --param name="" - -# 6. Preview before execution -apm preview start --param name="" - -# 7. List available prompts -apm list -``` - -## Tips & Best Practices - -1. **Start with runtime setup**: Run `apm runtime setup copilot` -2. **Use GitHub Models for free tier**: Set `GITHUB_TOKEN` (user-scoped with Models read permission) for free Codex access -3. **Discover MCP servers**: Use `apm mcp search` to find available MCP servers before adding to apm.yml -4. **Preview before running**: Use `apm preview` to check parameter substitution -5. **Organize prompts**: Use descriptive names and place in logical directories -6. **Version control**: Include `.prompt.md` files and `apm.yml` in your git repository -7. **Parameter naming**: Use clear, descriptive parameter names in prompts -8. **Error handling**: Always check return codes in scripts and CI/CD -9. **MCP integration**: Declare MCP dependencies in both `apm.yml` and prompt frontmatter - -## Integration Examples - -### In CI/CD (GitHub Actions) -```yaml -- name: Setup APM runtime - run: | - apm runtime setup codex - # Purpose-specific authentication - export GITHUB_APM_PAT=${{ secrets.GITHUB_APM_PAT }} # Private modules + fallback - export GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} # Optional: Codex CLI with GitHub Models - -- name: Setup APM project - run: apm install - -- name: Run code review - run: | - apm run code-review \ - --param pr_number=${{ github.event.number }} -``` - -### In Development Scripts -```bash -#!/bin/bash -# Setup and run APM project -apm runtime setup codex -# Fine-grained token preferred -export GITHUB_APM_PAT=your_fine_grained_token # Private modules + fallback auth -export GITHUB_TOKEN=your_models_token # Codex CLI with GitHub Models - -cd my-apm-project -apm install - -# Run documentation analysis -if apm run document --param project_name=$(basename $PWD); then - echo "Documentation analysis completed" -else - echo "Documentation analysis failed" - exit 1 -fi -``` - -### Project Structure Example -``` -my-apm-project/ -├── apm.yml # Project configuration -├── README.md # Project documentation -├── hello-world.prompt.md # Main prompt file -├── prompts/ -│ ├── code-review.prompt.md # Code review prompt -│ └── documentation.prompt.md # Documentation prompt -└── .github/ - └── workflows/ - └── apm-ci.yml # CI using APM prompts -```