Amplifier CLI

September 10, 2026 · View on GitHub

Command-line interface for the Amplifier AI-powered modular development platform.

Note: This is a reference implementation of an Amplifier CLI. It works with amplifier-core and demonstrates how to build a CLI around the kernel. You can use this as-is, fork it, or build your own CLI using the core.

Installation

For Users

# Try without installing
uvx --from git+https://github.com/microsoft/amplifier amplifier

# Install globally
uv tool install git+https://github.com/microsoft/amplifier

Quick Start

# First-time setup — opens a combined dashboard to add providers,
# select a routing matrix, and verify configuration (auto-runs if no config)
amplifier init

# Tip: Set environment variables for faster setup
# export ANTHROPIC_API_KEY="your-key"
# The dashboard detects env vars and shows them as defaults

# Install shell completion (optional, one-time setup)
amplifier --install-completion

# Single command (uses anchors bundle by default)
amplifier run "Create a Python function to calculate fibonacci numbers"

# Single command via stdin (useful for scripts/pipelines)
echo "Summarize this spec" | amplifier run

# Interactive chat mode
amplifier

# Use specific bundle
amplifier run --bundle my-bundle "Your prompt"

Environment variables: ANTHROPIC_API_KEY, OPENAI_API_KEY, AZURE_OPENAI_API_KEY, GOOGLE_API_KEY detected automatically during amplifier init.

Commands

Configuration Commands

# Bundle management (primary configuration method)
amplifier bundle current                              # Show active bundle
amplifier bundle use <name> [--local|--project|--global]  # Set active bundle
amplifier bundle list                                 # List available bundles
amplifier bundle show <name>                          # Show bundle details
amplifier bundle add <git-url> [--name alias]         # Register a bundle (name auto-derived)
amplifier bundle remove <name>                        # Unregister a bundle
amplifier bundle clear                                # Reset to default (anchors)

# Provider management
amplifier provider add <name> [--local|--project|--global]  # Add/configure a provider
amplifier provider list                                      # List configured providers
amplifier provider remove <name> [--scope]                   # Remove a provider
amplifier provider edit <name>                               # Edit provider configuration
amplifier provider test [<name>]                             # Test provider connectivity
amplifier provider manage                                    # Interactive provider dashboard

# Routing matrix management
amplifier routing list                                       # List available matrices
amplifier routing use <name> [--local|--project|--global]    # Select active matrix
amplifier routing show [<name>]                              # Show resolved roles for a matrix
amplifier routing manage                                     # Interactive routing dashboard

# Module management
amplifier module add <name> [--local|--project|--global]
amplifier module remove <name> [--scope]
amplifier module current
amplifier module list
amplifier module show <name>
amplifier module refresh [<name>] [--mutable-only]
amplifier module check-updates

# Source management
amplifier source add <id> <uri> [--local|--project|--global]
amplifier source remove <id> [--scope]
amplifier source list
amplifier source show <id>

# Notification settings (requires notify bundle)
amplifier notify status                              # Show current notification settings
amplifier notify desktop --enable [--scope]          # Enable desktop/terminal notifications
amplifier notify desktop --disable [--scope]         # Disable desktop notifications
amplifier notify ntfy --enable --topic <topic>       # Enable ntfy.sh push notifications
amplifier notify ntfy --disable [--scope]            # Disable push notifications
amplifier notify reset --all [--scope]               # Clear all notification settings

Note on extra_request_params: some provider modules support an extra_request_params key inside a provider's config block -- a raw, user-owned dict of request parameters merged verbatim into every API call for options the module doesn't wrap itself. It is entirely your responsibility to maintain by hand in settings.yaml; config tooling (provider add/provider edit/provider manage) round-trips it untouched across reconfigures but never prompts for it, displays it in the wizard, or validates its contents.

Session Commands

# New sessions
amplifier run "prompt"                    # Single-shot (auto-persists, shows ID)
amplifier                                 # Interactive (auto-generates ID)

# Runtime overrides (highest priority, override all config levels)
amplifier run -p anthropic "prompt"              # Use specific provider
amplifier run -m claude-sonnet-4-5 "prompt"      # Use specific model
amplifier run --max-tokens 500 "prompt"          # Limit output tokens
amplifier run -p openai -m gpt-5.2 --max-tokens 1000 "prompt"  # Combine flags

# Resume workflows
amplifier continue                        # Resume most recent (interactive)
amplifier continue "new prompt"           # Resume most recent (single-shot)
amplifier run --resume <id> "prompt"      # Resume specific session
echo "prompt" | amplifier continue        # Resume via Unix pipe

# Session management
amplifier session list                    # Recent sessions
amplifier session show <id>               # Session details
amplifier session resume <id>             # Resume specific (interactive)
amplifier session delete <id>             # Delete session
amplifier session cleanup [--days N]      # Clean up old sessions

Conversational Single-Shot Workflows

Build context across multiple commands:

# Question 1: Start conversation
$ amplifier run "What's the weather in Seattle?"
Session ID: a1b2c3d4
[Response about Seattle weather]

# Question 2: Follow-up with context
$ amplifier continue "And what about tomorrow?"
✓ Resuming most recent session: a1b2c3d4
  Messages: 2
[Response with context from previous question]

# Question 3: Continue the thread
$ amplifier continue "Should I bring an umbrella?"
✓ Resuming most recent session: a1b2c3d4
  Messages: 4
[Response informed by entire weather conversation]

Unix piping with context:

# Initial question
$ amplifier run "Analyze this log file structure"
Session ID: e5f6g7h8
[Analysis]

# Follow-up via pipe
$ cat errors.log | amplifier continue
✓ Resuming most recent session: e5f6g7h8
  Messages: 2
[Analysis of errors with context from previous conversation]

Resume specific conversation:

# List your sessions
$ amplifier session list
Recent Sessions:
  a1b2c3d4  2024-11-10 14:30  6 messages  # Weather conversation
  e5f6g7h8  2024-11-10 12:15  4 messages  # Log analysis

# Resume the weather conversation specifically
$ amplifier run --resume a1b2c3d4 "What about next week?"
✓ Resuming session: a1b2c3d4
  Messages: 6
[Response with full weather conversation context]

Tool Commands

# List tools available in the active bundle (shows actual tool names)
amplifier tool list                               # Table format (mounts tools)
amplifier tool list --modules                     # Show module names (fast, no mount)
amplifier tool list --bundle my-bundle            # Specify bundle
amplifier tool list --output json                 # JSON format

# Show details about a specific tool
amplifier tool info <tool-name>                   # Show tool info
amplifier tool info read_file --bundle my-bundle  # With specific bundle
amplifier tool info --module tool-filesystem      # Show module info (fast)

# Invoke a tool directly with arguments
amplifier tool invoke read_file file_path=/tmp/test.txt
amplifier tool invoke bash command="ls -la"
amplifier tool invoke web_fetch url="https://example.com"

Note: Tool modules (e.g., tool-filesystem) expose multiple actual tools (e.g., read_file, write_file, edit_file). Use amplifier tool list to see actual tool names, or --modules for a fast module-level view.

Utility Commands

amplifier init                                     # First-time setup (combined dashboard)
amplifier update [--check-only] [--force] [-y]    # Update Amplifier and modules
amplifier --install-completion                     # Set up tab completion
amplifier --version                                # Show version
amplifier --help                                   # Show help

Update command options:

--check-only: Check for updates without installing
--force: Force update all sources (skip update detection)
-y, --yes: Skip confirmation prompts
--verbose: Show detailed multi-line output per source (default: concise one-line format)

Shell Completion

Enable tab completion with one command. Amplifier automatically installs completion for standard shell setups.

One-Command Installation

amplifier --install-completion

What happens:

Detects your shell (bash, zsh, or fish) from $SHELL
Automatically appends the completion line to your shell config:
- Bash: ~/.bashrc; an existing profile-only setup keeps ~/.bash_profile
- Zsh: ~/.zshrc
- Fish: ~/.config/fish/completions/amplifier.fish
Checks if already installed (safe to run multiple times)
Falls back to manual instructions if custom configuration detected

Output (standard setup):

Detected shell: bash
✓ Added completion to /home/user/.bashrc

To activate:
  source ~/.bashrc

Or start a new terminal.

Output (already installed):

Detected shell: bash
✓ Completion already configured in /home/user/.bashrc

Command and Local Value Completion

Once active, tab completion works throughout the CLI:

amplifier bun<TAB>         # Completes to "bundle"
amplifier bundle u<TAB>    # Completes to "use"
amplifier bundle use <TAB> # Shows local available bundles
amplifier run --<TAB>      # Shows all options

Amplifier supports Bash, Zsh, and Fish, not PowerShell. In addition to command names, flags, and fixed choices, it suggests locally known top-level bundle names, configured provider instance names, and the newest 100 matching top-level sessions for the current project. Lookup is read-only and local: it does not fetch bundles, initialize providers, call model/provider APIs, or inspect session transcript/event content. Suggestions are advisory; unknown bundle, provider, and session values remain valid command input where the command normally accepts them.

Your shell controls the completion menu and key behavior. This is separate from the interactive ui.slash_popup.enabled setting below. Zsh users must enable the standard compinit setup in .zshrc; the installer does not add it. Use the printed source command for the current terminal. Automatic loading in a new Bash terminal depends on that terminal reading the selected startup file; login-shell setups may need to source .bashrc from their profile. Nested bundle names, URIs, and names containing shell-special characters can still be entered manually. The installer preserves user-written Fish completion files and offers a temporary | source command instead of overwriting them.

Interactive Slash Completion

Inside an interactive Amplifier session, typing a leading / automatically opens command menus and known argument-choice menus; Tab completes commands and their currently available arguments. The menu includes short descriptions and is based on the mounted providers, modes, skills, and live configuration captured before the prompt opens.

Tab completes the unambiguous part whether or not a menu is open: one match is accepted with its trailing space; several matches extend their shared prefix and remain unselected. Repeating Tab does not cycle choices.
Up/Down and Shift-Tab select an open menu item. Tab, Enter, or Space accepts an explicitly selected item without submitting the prompt.
Enter accepts an exact command name (or one unique command match). For an ambiguous command prefix it keeps the menu open and asks you to type more or choose. An unselected argument menu always submits the exact text you typed.
Esc cancels an open menu and restores the text from before completion.
For example, with /product-council, /product-council-here, and /provider available, /p + Tab becomes /pro; /pro + Tab remains /pro until you type more or select a choice. /provider + Tab opens its known argument choices.
/exit ends the interactive session; /quit is an alias. Neither accepts arguments.

Automatic slash menus are on by default. To disable all automatic command and argument popups, add this to ~/.amplifier/settings.yaml:

ui: {slash_popup: {enabled: false}}

Tab completion, including command arguments and aliases, remains available. enabled must be the YAML boolean false, not the string "false". The setting applies to fresh and resumed interactive sessions started after the change; restart the interactive session to pick it up.

Completion is available for built-in slash commands, provider and mode controls, /config verbs/flags, user-invocable skills and their declared literal arguments, and /goal controls. The catalog is conditional on the commands, modes, skills, and providers mounted in the live session. Free-form prompt text, goal conditions, and file/path arguments are intentionally not guessed.

Architecture

This CLI is built on top of amplifier-core and provides:

Bundle system - Composable configuration packages (via amplifier-foundation)
Settings management - Three-scope configuration (local/project/global via amplifier-config)
Module resolution - Module source resolution for tools, providers, hooks
Session storage - Project-scoped session persistence with multi-turn sub-session resumption
Agent delegation - Spawn and resume sub-sessions for iterative collaboration with specialized agents
Interactive mode - REPL with slash commands
Key management - Secure API key storage

Supported Providers

Anthropic Claude - Recommended, most tested (Sonnet, Opus models)
OpenAI - Good alternative (GPT-4o, GPT-4o-mini, o1 models)
Azure OpenAI - Enterprise users with Azure subscriptions
Google Gemini - Google's AI models with large context windows (Gemini 2.5 Flash, Pro)
Ollama - Local, free, no API key needed

Provider sources

amplifier provider add … pins the canonical module source for each first-party provider (for example, the OpenAI provider resolves to git+https://github.com/microsoft/amplifier-module-provider-openai@main). Existing installations inherit these canonical URIs at runtime as well, so fresh environments download the provider code via uv automatically. No manual source overrides are required for the built-in providers.

Development

Prerequisites

Python 3.11+
UV package manager

Setup

cd amplifier-app-cli
uv pip install -e .
uv run pytest

Project Structure

amplifier_app_cli/
├── commands/          # CLI command implementations (provider, bundle, init, logs, setup)
├── data/
│   └── context/       # Bundled context files
├── lib/               # Shared libraries
│   └── mention_loading/ # @mention expansion system
├── utils/             # Utility functions
├── banners/           # Banner art
├── paths.py           # Path configuration and factory functions
├── key_manager.py     # API key management
├── provider_manager.py # Provider configuration
├── module_manager.py  # Module management
├── session_store.py   # Session persistence (transcript, metadata, state)
├── session_spawner.py # Agent delegation (spawn and resume sub-sessions)
├── agent_config.py    # Agent configuration utilities
└── main.py            # CLI entry point

toolkit/               # Standalone scenario tool utilities (at repo root)
├── utilities/         # Structural utilities (file ops, progress, validation)
├── examples/          # Example tools (tutorial_analyzer)
└── templates/         # Tool templates

Note: Core functionality provided by libraries:

amplifier-foundation - Bundle loading and composition (primary)
amplifier-config - Settings management

Documentation

CLI-Specific Docs (in this repo):

Agent Delegation - Sub-session spawning and resumption
Context Loading - @mention system implementation
Interactive Mode - REPL and slash commands
Architectural Decisions - ADRs for major design choices

Authoritative Guides (external, maintained in library repos):

→ Bundle Guide - Creating and managing bundles
→ User Onboarding - Complete user guide and reference

Toolkit (for building sophisticated tools):

Contributing

Note

This project is not currently accepting external contributions, but we're actively working toward opening this up. We value community input and look forward to collaborating in the future. For now, feel free to fork and experiment!

Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Contributor License Agreements.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

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. 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.