Skip to main content

CLI Commands

Complete reference for all Pixell Agent Kit (PAK) CLI commands. Use these commands to create, develop, test, and package your AI agents.

Command Overview​

pixell [OPTIONS] COMMAND [ARGS]...

Global Options​

OptionDescriptionExample
--helpShow help messagepixell --help
--versionShow version informationpixell --version
--verboseEnable verbose outputpixell --verbose run-dev
--config FILEUse custom config filepixell --config my-config.json build

Core Commands​

pixell init​

Create a new agent project with the standard structure.

pixell init [OPTIONS] PROJECT_NAME

Options:

  • --template TEMPLATE - Choose template: basic (default) or advanced
  • --description TEXT - Set project description
  • --author TEXT - Set project author
  • --version TEXT - Set initial version (default: 0.1.0)

Examples:

# Basic agent
pixell init my-agent

# Advanced agent with custom options
pixell init my-agent --template advanced --description "My AI Agent" --author "John Doe"

# With specific version
pixell init my-agent --version 1.0.0

Creates:

my-agent/
├── agent.yaml              # Agent manifest
├── README.md               # Project documentation
├── .env.example           # Environment variables template
├── requirements.txt        # Python dependencies
├── src/
│   ├── main.py            # Main entry point
│   ├── a2a/               # A2A service implementation
│   │   └── service.py
│   └── rest/              # REST API routes
│       └── routes.py
└── ui/
    └── index.html         # Web UI (optional)

pixell run-dev​

Start the local development server with hot-reload.

pixell run-dev [OPTIONS]

Options:

  • --port PORT - Server port (default: 8000)
  • --host HOST - Server host (default: localhost)
  • --reload - Enable hot-reload (default: true)
  • --debug - Enable debug mode

Examples:

# Default development server
pixell run-dev

# Custom port
pixell run-dev --port 3000

# Production-like server
pixell run-dev --host 0.0.0.0 --port 8080 --reload false

Features:

  • 🔥 Hot-reload - Automatically restart on code changes
  • 📊 Live logs - Real-time request/response logging
  • 🐛 Debug mode - Detailed error information
  • 🌐 Multi-surface - REST, A2A, and UI endpoints

pixell build​

Build the agent into an APKG (Agent Package) file.

pixell build [OPTIONS]

Options:

  • --output-dir DIR - Output directory (default: ./dist)
  • --version VERSION - Override version from manifest
  • --include-dev - Include development dependencies
  • --compress - Compress the APKG file
  • --sign - Sign the APKG file

Examples:

# Standard build
pixell build

# Custom output directory
pixell build --output-dir ./packages

# With version override
pixell build --version 2.0.0

# Compressed build
pixell build --compress

Output:

dist/
└── my-agent-0.1.0.apkg    # Portable agent package

pixell inspect​

Inspect the contents of an APKG file.

pixell inspect [OPTIONS] APKG_FILE

Options:

  • --format FORMAT - Output format: table (default), json, yaml
  • --show-files - Show file listing
  • --show-manifest - Show manifest contents
  • --validate - Validate package integrity

Examples:

# Basic inspection
pixell inspect my-agent-0.1.0.apkg

# JSON output
pixell inspect my-agent-0.1.0.apkg --format json

# Detailed inspection
pixell inspect my-agent-0.1.0.apkg --show-files --show-manifest

Output:

APKG Package: my-agent-0.1.0.apkg
├── Name: my-agent
├── Version: 0.1.0
├── Size: 2.3 MB
├── Created: 2024-01-15 10:30:00
└── Files: 15 files

pixell validate​

Validate agent configuration and dependencies.

pixell validate [OPTIONS]

Options:

  • --strict - Enable strict validation
  • --check-deps - Validate dependencies
  • --check-manifest - Validate manifest only
  • --fix - Auto-fix common issues

Examples:

# Standard validation
pixell validate

# Strict validation
pixell validate --strict

# Auto-fix issues
pixell validate --fix

Validation checks:

  • ✅ Manifest syntax and required fields
  • ✅ Python dependencies resolution
  • ✅ File structure compliance
  • ✅ Environment variable configuration
  • ✅ API endpoint definitions

pixell config​

Manage configuration settings.

pixell config [OPTIONS] COMMAND [ARGS]...

Subcommands:

pixell config init​

Initialize configuration file.

pixell config init [OPTIONS]

Options:

  • --file FILE - Config file path (default: pixell.json)
  • --interactive - Interactive setup

pixell config set​

Set configuration value.

pixell config set KEY VALUE

Examples:

# Set default port
pixell config set server.port 3000

# Set build options
pixell config set build.compress true

pixell config get​

Get configuration value.

pixell config get KEY

Examples:

# Get current port
pixell config get server.port

# Get all settings
pixell config get

pixell config list​

List all configuration settings.

pixell config list

Development Commands​

pixell test​

Run agent tests (if test framework is configured).

pixell test [OPTIONS]

Options:

  • --coverage - Generate coverage report
  • --verbose - Verbose test output
  • --pattern PATTERN - Test file pattern

pixell lint​

Lint agent code for style and quality issues.

pixell lint [OPTIONS]

Options:

  • --fix - Auto-fix linting issues
  • --strict - Enable strict linting rules

pixell format​

Format agent code according to style guidelines.

pixell format [OPTIONS]

Options:

  • --check - Check formatting without making changes
  • --diff - Show formatting differences

Utility Commands​

pixell env​

Manage environment variables.

pixell env [OPTIONS] COMMAND [ARGS]...

Subcommands:

  • pixell env list - List environment variables
  • pixell env set KEY VALUE - Set environment variable
  • pixell env unset KEY - Unset environment variable
  • pixell env load FILE - Load from .env file

pixell logs​

View and manage agent logs.

pixell logs [OPTIONS]

Options:

  • --follow - Follow log output
  • --tail N - Show last N lines
  • --level LEVEL - Filter by log level

pixell status​

Show agent status and health.

pixell status [OPTIONS]

Shows:

  • 🟢 Agent health status
  • 📊 Resource usage
  • 🔗 Active endpoints
  • 📈 Performance metrics

Advanced Usage​

Command Chaining​

Chain commands for complex workflows:

# Create, validate, and build in one go
pixell init my-agent && pixell validate && pixell build

# Development workflow
pixell run-dev --port 3000 &
pixell test --coverage
pixell build --compress

Configuration Files​

PAK supports multiple configuration formats:

pixell.json:

{
  "server": {
    "port": 8000,
    "host": "localhost"
  },
  "build": {
    "compress": true,
    "includeDev": false
  }
}

pixell.yaml:

server:
  port: 8000
  host: localhost
build:
  compress: true
  includeDev: false

Environment Variables​

Override any setting with environment variables:

# Override port
PIXELL_SERVER_PORT=3000 pixell run-dev

# Override build options
PIXELL_BUILD_COMPRESS=true pixell build

Error Handling​

Common Error Codes​

CodeDescriptionSolution
E001Invalid manifestCheck agent.yaml syntax
E002Missing dependenciesRun pip install -r requirements.txt
E003Port already in useUse --port to specify different port
E004Invalid APKG formatRebuild with pixell build

Debug Mode​

Enable debug mode for detailed error information:

# Global debug
pixell --verbose run-dev

# Command-specific debug
pixell run-dev --debug

Getting Help​

Command Help​

# General help
pixell --help

# Command-specific help
pixell init --help
pixell build --help

Documentation​

Next Steps: