Installation¶

This page covers everything you need to install AAM, verify the installation, configure your environment, and set up shell completions.

System Requirements¶

Before installing AAM, ensure your system meets these requirements:

Check your Python version:

python --version

Install AAM¶

Option 1: Install Globally¶

Install AAM globally with pip:

pip install aam

This makes the aam command available system-wide.

Option 2: Install in a Virtual Environment (Recommended)¶

Using a virtual environment keeps your system Python clean and avoids dependency conflicts:

# Create a virtual environment
python -m venv ~/.aam-venv

# Activate it
source ~/.aam-venv/bin/activate  # On macOS/Linux
# Or on Windows:
# .\.aam-venv\Scripts\activate

# Install AAM
pip install aam

# Add to ~/.bashrc or ~/.zshrc
alias aam='~/.aam-venv/bin/aam'

Option 3: Install from Source¶

For development or to get the latest unreleased features:

git clone https://github.com/spazyCZ/agent-package-manager.git
cd agent-package-manager
pip install -e .

Verify Installation¶

Confirm that AAM is installed and accessible:

aam --version

Expected output:

aam 0.1.0

If the aam command is not found:

1. Ensure your Python scripts directory is on your PATH
2. If using a virtual environment, make sure it's activated
3. Try python -m aam --version as a fallback

Get help on available commands:

aam --help

First-Time Configuration¶

Set Your Default Platform¶

AAM deploys artifacts to AI platforms like Cursor, Claude, GitHub Copilot, or Codex. Set your default platform so you don't need to specify it on every command:

aam config set default_platform cursor

Supported platforms:

You can always override this per-command with --platform:

aam install @author/some-skill --platform copilot

Set Your Author Name¶

When creating packages, AAM uses your author name in the package metadata:

aam config set author.name "Your Name"
aam config set author.email "you@example.com"

This information appears in published packages and helps users identify package authors.

View Your Configuration¶

Check all current settings:

aam config list

Example output:

default_platform: cursor
author:
  name: Your Name
  email: you@example.com

Set Up a Registry¶

A registry is where AAM stores and discovers packages. The fastest way to get started is with a local file-based registry — no server required.

Create a Local Registry¶

Initialize a new registry directory:

# Create a registry directory
aam registry init ~/my-packages

Expected output:

Created local registry at /home/user/my-packages

Register it with AAM and set it as the default:

aam registry add local file:///home/user/my-packages --default

Expected output:

Added registry 'local' (file:///home/user/my-packages)
Set 'local' as default registry

Verify Registry Configuration¶

List all configured registries:

aam registry list

Example output:

Name     Type    URL                                Default
----     ----    ---                                -------
local    file    file:///home/user/my-packages      yes

Connect to a Remote Registry (Optional)¶

If your team has an HTTP registry server:

aam registry add company https://aam.company.com --default

Then log in with your credentials:

aam login company

Shell Completion¶

AAM supports tab completion for commands, options, and package names. Enable it for your shell:

# Add completion to your bashrc
aam completion bash >> ~/.bashrc

# Reload your shell
source ~/.bashrc

# Add completion to your zshrc
aam completion zsh >> ~/.zshrc

# Reload your shell
source ~/.zshrc

# Install completion for Fish
aam completion fish > ~/.config/fish/completions/aam.fish

# Fish will automatically load it

After setup, try typing aam and pressing Tab to see available commands.

Example:

aam in<TAB>

Expands to:

aam install

Configuration File Locations¶

AAM stores configuration in the following locations:

Global Configuration¶

Project Configuration¶

Each project can have its own configuration in:

.aam/config.yaml

Project settings override global settings.

Credentials¶

API tokens and login credentials are stored separately:

Upgrading AAM¶

To upgrade to the latest version:

pip install --upgrade aam

Check the changelog for breaking changes:

aam changelog

Or visit the GitHub releases page.

Uninstalling AAM¶

To remove AAM:

pip uninstall aam

To also remove configuration and cache:

# Remove global configuration
rm -rf ~/.config/aam/

# Remove cache
rm -rf ~/.cache/aam/

Troubleshooting¶

Command Not Found¶

If aam is not found after installation:

1. Check Python scripts directory is on PATH:

   python -m site --user-base
   

   Add <output>/bin to your PATH.

2. Use the module syntax:

   python -m aam --version
   

3. Reinstall with --user flag:

   pip install --user aam
   

Permission Errors¶

If you get permission errors during installation:

# Use --user flag to install in your home directory
pip install --user aam

Import Errors¶

If you see ModuleNotFoundError after installation:

# Ensure pip is using the same Python as your shell
python -m pip install aam

Next Steps¶

AAM is now installed and configured. Continue with:

• Quick Start — Create, publish, and install your first package in 5 minutes
• Your First Package — Build a complete package with all artifact types
• CLI Reference — Explore all available commands