CLI configuration

This page documents how the Amplifier CLI assembles its effective configuration: where it reads settings from, which files exist at user vs project scope, which environment variables override which parts, and what defaults apply.

Three different "config surfaces"
The CLI's behavior comes from three inputs that are easy to conflate:
  • Settings (settings.yaml): select bundle, register module sources, set overrides.
  • Bundles: the actual mount plan content (providers/tools/hooks/agents/system instructions).
  • Environment variables: last-mile overrides (especially module resolution and credentials).
Profiles & Collections (Deprecated)

Older versions used profiles and collections. These still work but are deprecated.

For new projects: Use bundles exclusively. See Bundle fundamentals.

For existing projects: See migration guide.

Where the CLI reads and writes

The CLI uses a “project + user” directory convention (plus a local settings file for machine-specific overrides).

User home (~/.amplifier/)

Project workspace (.amplifier/)

Settings files and precedence

The CLI uses the amplifier-config library (three-scope configuration) with CLI-specific paths and guardrails.

Code references: amplifier-app-cli/amplifier_app_cli/paths.py, amplifier-config/src/amplifier_config/manager.py.

Settings schema (what keys exist)

Settings are YAML. The CLI reads several top-level keys to determine bundle/module configuration.

Current (Bundle-Based) Configuration

# ~/.amplifier/settings.yaml (recommended for new projects)

# 1) Active bundle (primary configuration)
bundle:
  active: foundation  # or recipes, design-intelligence, lsp-python, etc.

# 2) Module source overrides (optional)
sources:
  tool-bash: /home/me/dev/amplifier-module-tool-bash  # Local development
  provider-anthropic: git+https://github.com/microsoft/amplifier-module-provider-anthropic@main

# 3) Provider configuration (optional, often set in bundle)
config:
  providers:
    - module: provider-anthropic
      config:
        default_model: claude-sonnet-4-5
        api_key: ${ANTHROPIC_API_KEY}  # From environment

# 4) Registered modules (additional modules beyond bundle)
modules:
  tools:
    - module: tool-my-custom
      source: git+https://github.com/me/tool-custom@main
  hooks:
    - module: hooks-my-logging
      source: /home/me/dev/my-hooks

Legacy (Deprecated) Configuration

# OLD STYLE - Still works but deprecated

# Profile selection (replaced by bundles)
profile:
  active: developer-expertise:dev
  default: developer-expertise:dev

# Collection source overrides (replaced by bundles)
collection_sources:
  toolkit: /home/me/dev/amplifier-collection-toolkit

These settings still function but will be removed in a future version. Migrate to bundles.

Configuration Precedence

When the CLI determines what to run:

  1. Bundle (if set) - bundle.active takes precedence
  2. Profile (if no bundle) - Falls back to profile.active (deprecated)
  3. Module overrides - Settings can override individual modules from bundle
  4. Environment variables - Final override layer
Recommendation
For new projects, only use bundle.active. Avoid mixing bundles and profiles in the same project.

Code reference for the overlay behavior: amplifier-app-cli/amplifier_app_cli/runtime/config.py.

How the CLI picks profile vs bundle

The run command decides your configuration source in this order:

  1. --bundle (explicit bundle mode)
  2. bundle.active in merged settings (bundle mode opt-in)
  3. --profile (profile override for this run)
  4. profile.active in settings (local > project > user)
  5. System default (compiled into the CLI package)

The system default profile is read from amplifier_app_cli/data/profiles/DEFAULTS.yaml.

Module resolution and overrides (what wins)

The CLI mounts a resolver from amplifier-module-resolution, which uses a fixed resolution order. This is what makes “I’m developing module X locally” work without changing profiles.

  1. Environment: AMPLIFIER_MODULE_<MODULE_ID>=<source>
  2. Workspace convention: .amplifier/modules/<module_id>/
  3. Settings: sources: and modules.*[].source from settings
  4. Collections: modules packaged inside installed collections
  5. Profile hint: source: specified in the profile/bundle
  6. Installed package: entry points from installed Python packages

Code references: CLI wiring in paths.py, amplifier-module-resolution/src/.../resolvers.py.

Provider credentials: keys.env and env vars

The CLI loads ~/.amplifier/keys.env on startup and injects any key/value pairs into the process environment if they’re not already set.

Code reference: amplifier_app_cli/key_manager.py. 

# Example keys.env entries (written by CLI commands)
ANTHROPIC_API_KEY="..."
OPENAI_API_KEY="..."
AZURE_OPENAI_ENDPOINT="https://...openai.azure.com"
Provider-specific env vars
Each provider module declares which environment variables it uses (e.g., ANTHROPIC_API_KEY). The set of credential env vars is provider-specific and lives in provider module code, not in the CLI.

Environment variables used by the CLI ecosystem

Env var Where it applies What it does
AMPLIFIER_HOME Bundles / foundation Overrides the default home directory used by foundation’s bundle registry and caches (default: ~/.amplifier).
AMPLIFIER_MODULE_<ID> Module resolution Highest-precedence module source override (beats workspace/settings/collections/profile).
AMPLIFIER_MODULES Kernel fallback Colon-separated search paths for module discovery when no source resolver is mounted (entry points + filesystem scan).
AMPLIFIER_AGENT_<NAME> Agent resolution Overrides an agent file path (used by agent resolver; useful for local agent development).
AMPLIFIER_BANNER_STYLE CLI UX Selects interactive banner style (e.g. matrix, retro).
_AMPLIFIER_COMPLETE CLI UX Shell completion plumbing used by the CLI completion integration.
SHELL CLI UX Used to auto-detect your shell when printing completion setup instructions.
AMPLIFIER_GIT_HOST Module downloads Rewrites GitHub URLs to a shadow git host for isolated/test environments.
GITHUB_TOKEN Module downloads / status Used for GitHub API access (e.g. update checks and certain resolver behaviors).

Env var expansion inside settings

The CLI expands ${VAR} and ${VAR:default} inside the resolved config right before session creation. This is primarily used for credential injection without committing secrets. 

config:
  providers:
    - module: provider-anthropic
      config:
        default_model: claude-sonnet-4-5
        api_key: ${ANTHROPIC_API_KEY:}

Code reference: expand_env_vars().

Additional references: foundation: get_amplifier_home(), core: AMPLIFIER_MODULES discovery.

Important markdown files the CLI can load

The CLI is not “just a prompt runner”: it resolves profiles, agents, and bundle resources from the filesystem and can also resolve @mentions that include markdown files into prompts/context.

Code references: amplifier-profiles agent resolver, CLI mention resolver.

AGENTS.md (why it feels “special”)
In the default profiles, AGENTS.md is referenced via @mentions and can be pulled into the session’s system message by the CLI’s mention expansion. See AGENTS.md Loading.