ayaiay CLI

The ayaiay CLI is a command-line tool for discovering, installing, and managing AI agent packs from your terminal.

What is the CLI?

The ayaiay CLI provides a streamlined way to interact with the ayaiay ecosystem without using the web interface. It's perfect for:

• Automation: Integrate pack management into scripts and CI/CD pipelines
• Local Development: Quickly install and test packs during development
• Terminal Workflows: Stay in your terminal while working with AI resources
• Package Management: Track dependencies with ayaiay.json lock files
• Offline Validation: Validate pack manifests before publishing

Key Features

Search and Discovery

Search for packs directly from your terminal with fuzzy matching and filtering by type and tags.

Pack Installation

Install packs to your local system with version control and dependency management.

Package Management with ayaiay.json

Track all your project's pack dependencies with versions in a lock file, similar to package.json or composer.json.

Manifest Validation

Validate ayaiay.yaml files to ensure they meet the specification before publishing.

Fast and Lightweight

Written in Python with minimal dependencies, the CLI is fast and easy to install.

Quick Start

Installation

⚠️ Note: The package is not yet published to PyPI. The first release is pending.

Until then, install directly from GitHub:

pip install git+https://github.com/ayaiayorg/ayaiay-cli.git

Once published to PyPI (coming soon):

pip install ayaiay

# Verify installation
ayaiay --version

Basic Usage

# Search for packs
ayaiay search "code review"

# Install a pack
ayaiay install publisher/pack-name@1.0.0

# Initialize ayaiay.json lock file
ayaiay init

# Add pack to ayaiay.json and install it
ayaiay add publisher/pack-name

# Validate a manifest
ayaiay validate ayaiay.yaml

# List installed packs
ayaiay list

# Get pack information
ayaiay show publisher/pack-name

Core Concepts

Pack Identifiers

Packs are identified using the format:

publisher/pack-name@version

• publisher: The GitHub username or organization
• pack-name: The pack's unique name
• version: Semantic version (e.g., 1.0.0) or latest

Examples:

• acme/code-reviewer@1.2.0
• myorg/dev-tools@latest
• username/my-pack (implies @latest)

Installation Directory

By default, packs are installed to ~/.ayaiay/packs. You can customize this with the AYAIAY_INSTALL_DIR environment variable or in the config file.

API Configuration

The CLI connects to the ayaiay API to fetch pack metadata. Configure the API URL:

# Set globally via environment variable
export AYAIAY_API_URL=https://api.ayaiay.org

# Or override per command
ayaiay search "agent" --api-url https://api.ayaiay.org

Available Commands

search

Search for packs in the catalog.

ayaiay search [QUERY] [OPTIONS]

Options:

• --type, -t: Filter by type (agent, instruction, prompt)
• --tag, -g: Filter by tag (can be used multiple times)
• --limit, -l: Maximum number of results per page
• --page, -p: Page number
• --api-url TEXT: Override the API URL

Examples:

# Search for code review packs
ayaiay search "code review"

# Filter by type
ayaiay search --type agent

# Filter by tags
ayaiay search --tag python --tag testing

# Get more results
ayaiay search "agent" --limit 50

# Search all packs
ayaiay search

install

Install a pack from the catalog.

ayaiay install PACK [OPTIONS]

Options:

• --force, -f: Force reinstall (overwrite existing installation)

Examples:

# Install latest version
ayaiay install acme/code-reviewer

# Install specific version
ayaiay install acme/code-reviewer@1.0.0

# Force reinstall
ayaiay install acme/code-reviewer --force

init

Initialize a new ayaiay.json lock file in the current directory.

ayaiay init [OPTIONS]

Options:

• --path, -p PATH: Target directory for ayaiay.json (default: current directory)

Example:

# Initialize in current directory
ayaiay init

# Initialize in specific directory
ayaiay init --path /path/to/project

add

Add a pack to ayaiay.json and install it.

ayaiay add PACK [OPTIONS]

Options:

• --force, -f: Force reinstall
• --path, -p PATH: Target directory for ayaiay.json

Examples:

# Add and install latest version
ayaiay add acme/code-reviewer

# Add specific version
ayaiay add acme/code-reviewer@1.0.0

# Add to specific project
ayaiay add acme/code-reviewer --path /path/to/project

remove

Remove a pack from ayaiay.json and uninstall it.

ayaiay remove PACK [OPTIONS]

Options:

• --path, -p PATH: Target directory for ayaiay.json

Example:

ayaiay remove acme/code-reviewer

sync

Sync installed packs with ayaiay.json. This installs any packages listed in the lock file that aren't currently installed.

ayaiay sync [OPTIONS]

Options:

• --path, -p PATH: Target directory for ayaiay.json

Example:

# Useful after cloning a project with ayaiay.json
ayaiay sync

update

Update installed packs to the latest versions.

ayaiay update [PACK] [OPTIONS]

Options:

• --path, -p PATH: Target directory for ayaiay.json

Examples:

# Update all packs
ayaiay update

# Update specific pack
ayaiay update acme/code-reviewer

validate

Validate an ayaiay.yaml manifest file.

ayaiay validate MANIFEST_PATH [OPTIONS]

Options:

• --quiet, -q: Only show errors

Examples:

# Validate current directory
ayaiay validate ayaiay.yaml

# Validate specific file
ayaiay validate /path/to/pack/ayaiay.yaml

init-pack

Create a new pack manifest interactively with a guided wizard. No need to memorize the ayaiay.yaml schema!

ayaiay init-pack [OPTIONS]

Options:

• --path, -p PATH: Target directory for the pack (default: current directory)

Examples:

# Create pack in current directory
ayaiay init-pack

# Create pack in specific directory
ayaiay init-pack --path ./my-pack

What It Does:

The interactive wizard guides you through creating a complete, valid pack manifest by asking simple questions:

1. Pack Metadata: Name, description, author, license, repository, tags
2. Agents: Add AI agents with names, descriptions, and configurations
3. Instructions: Add reusable instruction sets
4. Prompts: Create prompt templates with variables
5. Skills: Define agent capabilities
6. Tools: Specify custom tools

Example Usage:

$ ayaiay init-pack --path ./my-pack

🎯 ayaiay Pack Creator - Interactive Wizard

=== Pack Metadata ===
Pack name: python-helper
Description: Python development assistant
Author: Dev Team
License [MIT]:
Repository URL: https://github.com/myorg/python-helper
Tags (comma-separated): python,development,testing

=== Agents ===
Add agents? [y/N]: y

Agent #1
  Name: code-reviewer
  Description: Reviews Python code for best practices
  System prompt: You are an expert Python developer...
  Model [gpt-4]:
  Temperature [0.7]:
  Tools (comma-separated) [read,search]: read,search,edit

Add another agent? [y/N]: n

✓ Created pack manifest: ./my-pack/ayaiay.yaml
✓ Manifest is valid!

Summary:
  📦 Pack: python-helper v1.0.0
  🤖 Agents: 1
  📋 Instructions: 0
  💬 Prompts: 0

Features:

• ✅ No Schema Knowledge Required: Just answer simple questions
• ✅ Automatic Validation: Validates the generated manifest immediately
• ✅ Fail-Safe: Won't overwrite existing manifests
• ✅ Smart Defaults: Pre-fills common values like MIT license
• ✅ Flexible Input: Comma-separated lists for tags, tools, variables
• ✅ Complete Output: Generates production-ready ayaiay.yaml

list

List all installed packs.

ayaiay list

Shows:

• Pack name and version
• Installation path
• Install date

show

Get detailed information about a pack.

ayaiay show PACK

Shows:

• Full description
• Available versions
• Contents (agents, instructions, prompts, MCP servers)
• Repository URL

Example:

ayaiay show acme/code-reviewer

info

Show current configuration and API status.

ayaiay info

Displays:

• Configuration values
• API connection status
• Installation directory

uninstall

Remove an installed pack.

ayaiay uninstall PACK

Example:

ayaiay uninstall acme/code-reviewer

Configuration

Environment Variables

Variable	Description	Default
AYAIAY_API_URL	Base URL for the ayaiay API	https://api.ayaiay.org
AYAIAY_REGISTRY_URL	OCI registry URL	ghcr.io/ayaiayorg
AYAIAY_INSTALL_DIR	Default installation directory	~/.ayaiay/packs
AYAIAY_CACHE_DIR	Cache directory	~/.ayaiay/cache
AYAIAY_TIMEOUT	Request timeout in seconds	30.0
AYAIAY_TOKEN	Authentication token (Bearer)	-

Configuration File

Create ~/.ayaiay/config.yaml for persistent settings:

api_base_url: https://api.ayaiay.org
registry_url: ghcr.io/ayaiayorg
install_dir: ~/.ayaiay/packs
cache_dir: ~/.ayaiay/cache
timeout: 30.0
# token: "<your-token>"

Notes:

• api_base_url must start with http:// or https://
• Directories are automatically created if they don't exist
• The token is used as a Bearer token in the Authorization header

Examples

Complete Workflow

# 1. Search for packs
ayaiay search "code review"

# 2. Get details about a pack
ayaiay show acme/code-reviewer

# 3. Install the pack
ayaiay install acme/code-reviewer@1.2.0

# 4. List installed packs
ayaiay list

# 5. Update to latest version
ayaiay update acme/code-reviewer

Package Management with ayaiay.json

Similar to package.json in Node.js or composer.json in PHP, you can use ayaiay.json to track all your project's pack dependencies:

# 1. Initialize a new project
ayaiay init

# 2. Add packs to your project
ayaiay add acme/code-reviewer
ayaiay add myorg/dev-tools@2.1.0

# 3. Commit ayaiay.json to version control
git add ayaiay.json
git commit -m "Add AI pack dependencies"

# 4. Team members can sync packs
git clone <your-repo>
cd <your-repo>
ayaiay sync

# 5. Update all packs to latest versions
ayaiay update

Example ayaiay.json:

{
  "version": "1.0",
  "packages": {
    "acme/code-reviewer": {
      "name": "acme/code-reviewer",
      "version": "1.2.0",
      "installed_at": "2024-01-15T10:30:00Z",
      "digest": "sha256:abc123...",
      "dependencies": {}
    }
  },
  "updated_at": "2024-01-15T10:30:00Z"
}

Working with Multiple Environments

# Development (local API)
export AYAIAY_API_URL=http://localhost:8000
ayaiay search "agent"

# Production
export AYAIAY_API_URL=https://api.ayaiay.org
ayaiay search "agent"

# One-time override
ayaiay search "agent" --api-url https://staging.ayaiay.org

Creating a New Pack

# 1. Create pack with interactive wizard
ayaiay init-pack --path ./my-agent-pack
# Follow the prompts to define your pack

# 2. Create the referenced files
cd my-agent-pack
mkdir -p agents instructions prompts
# Add your agent definitions, instructions, and prompts

# 3. Validate the manifest
ayaiay validate ayaiay.yaml

# 4. If valid, commit and tag
git init
git add .
git commit -m "Initial pack"
git tag v1.0.0
git push origin v1.0.0

# 5. Import via web UI or API

Validating Before Publishing

# Navigate to your pack directory
cd my-agent-pack

# Validate the manifest
ayaiay validate ayaiay.yaml

# If valid, commit and push
git tag v1.0.0
git push origin v1.0.0

# Then import via web UI or API

Troubleshooting

Command Not Found

If ayaiay command is not found after installation:

# Ensure Python scripts directory is in PATH
export PATH="$HOME/.local/bin:$PATH"

# Or reinstall with --user flag
pip install --user ayaiay

API Not Reachable

Symptoms:

• Unable to connect to the API
• API Status: Unreachable

Solutions:

# Check your internet connection
# Verify API URL
ayaiay info

# Set correct API URL
export AYAIAY_API_URL=https://api.ayaiay.org

# Test connectivity
curl https://api.ayaiay.org/api/v1/packs/stats

Authentication Errors

Symptoms:

• Authentication required or invalid token

Solutions:

# Set authentication token
export AYAIAY_TOKEN=your-token-here

# Or add to config file
echo "token: your-token-here" >> ~/.ayaiay/config.yaml

# Verify token in config
ayaiay info

Pack Not Found

Symptoms:

• Pack not found or Version not found

Solutions:

# Check pack name spelling
ayaiay search "pack-name"

# View available versions
ayaiay show publisher/pack-name

# Use exact version
ayaiay install publisher/pack-name@1.0.0

ayaiay.json Missing

Symptoms:

• No lock file found

Solutions:

# Initialize lock file
ayaiay init

# Or specify path
ayaiay init --path /path/to/project

Validation Errors

Common validation issues:

• Invalid YAML: Check syntax with a YAML validator
• Missing required fields: Ensure name, version, description, etc. are present
• Invalid version: Use semantic versioning (e.g., 1.0.0)
• Invalid paths: Verify all file paths referenced in the manifest exist

Example validation:

# Validate with detailed output
ayaiay validate ayaiay.yaml

# Quiet mode (only errors)
ayaiay validate ayaiay.yaml --quiet

Next Steps

• Pack Development - Build your first pack
• Publishing Guide - Share your packs
• API Reference - Programmatic access to the catalog
• Getting Started - Start using ayaiay