PAK CLI Reference

Complete command-line interface reference for PAK (Pixell Agent Kit) - the toolkit for building, packaging, and managing Pixell agents.

Note: This documentation is generated by AI based on the source code, and therefore it may have some incorrect knowledge of the project. In that case, please contact engineering@pixell.global

Overview

PAK provides a comprehensive CLI for agent development, building, and management. All commands follow the pattern:

pixell <command> [options] [arguments]

Global Options

These options are available for all PAK commands:

Option	Short	Description	Default
`--help`	`-h`	Show help information	-
`--version`	`-v`	Show version information	-
`--verbose`	`-V`	Enable verbose output	`false`
`--quiet`	`-q`	Suppress output (except errors)	`false`
`--config`	`-c`	Path to configuration file	`./pixell.yaml`
`--log-level`	`-l`	Set logging level	`info`

Commands

`init` - Initialize New Agent

Creates a new agent project with the standard structure.

pixell init [name] [options]

Arguments:

name - Agent name (optional, will prompt if not provided)

Options:

Option	Short	Description	Default
`--template`	`-t`	Template to use	`basic`
`--directory`	`-d`	Target directory	`./<name>`
`--force`	`-f`	Overwrite existing directory	`false`
`--no-git`		Skip git initialization	`false`

Examples:

# Initialize with prompt
pixell init

# Initialize with name
pixell init my-agent

# Use specific template
pixell init my-agent --template advanced

# Initialize in custom directory
pixell init my-agent --directory /path/to/agent

Templates:

basic - Simple agent with REST API
advanced - Agent with REST API, A2A, and UI
minimal - Minimal agent structure
custom - Custom template from URL

`build` - Build Agent Package

Builds an agent into an APKG (Agent Package) file.

pixell build [options]

Options:

Option	Short	Description	Default
`--output`	`-o`	Output file path	`./dist/<name>-<version>.apkg`
`--compress`	`-z`	Enable compression	`false`
`--optimize`		Enable optimizations	`false`
`--target`	`-t`	Build target	`production`
`--no-deps`		Skip dependency installation	`false`
`--clean`		Clean build directory first	`false`

Examples:

# Basic build
pixell build

# Build with compression
pixell build --compress

# Build for development
pixell build --target development

# Custom output path
pixell build --output ./releases/my-agent-v1.0.0.apkg

`run` - Run Agent Locally

Runs an agent in development mode with hot reloading.

pixell run [options]

Options:

Option	Short	Description	Default
`--port`	`-p`	Port to run on	`8080`
`--host`	`-H`	Host to bind to	`localhost`
`--reload`	`-r`	Enable hot reloading	`true`
`--debug`	`-d`	Enable debug mode	`false`
`--env`	`-e`	Environment file	`.env`

Examples:

# Run with defaults
pixell run

# Run on specific port
pixell run --port 3000

# Run in debug mode
pixell run --debug

# Run with custom environment
pixell run --env .env.production

`test` - Run Tests

Executes the agent's test suite.

pixell test [options] [pattern]

Arguments:

pattern - Test pattern to match (optional)

Options:

Option	Short	Description	Default
`--coverage`	`-c`	Generate coverage report	`false`
`--watch`	`-w`	Watch mode	`false`
`--verbose`	`-v`	Verbose output	`false`
`--parallel`	`-p`	Run tests in parallel	`true`
`--timeout`	`-t`	Test timeout (ms)	`5000`

Examples:

# Run all tests
pixell test

# Run specific test
pixell test test_agent.py

# Run with coverage
pixell test --coverage

# Watch mode
pixell test --watch

`validate` - Validate Agent

Validates agent configuration and code.

pixell validate [options]

Options:

Option	Short	Description	Default
`--strict`	`-s`	Strict validation	`false`
`--fix`	`-f`	Auto-fix issues	`false`
`--format`		Output format	`text`

Examples:

# Basic validation
pixell validate

# Strict validation
pixell validate --strict

# Auto-fix issues
pixell validate --fix

`deploy` - Deploy Agent

Deploys an agent to a PAR runtime.

pixell deploy [options] [target]

Arguments:

target - Deployment target (optional)

Options:

Option	Short	Description	Default
`--package`	`-p`	APKG file to deploy	`./dist/*.apkg`
`--runtime`	`-r`	PAR runtime URL	`http://localhost:8080`
`--token`	`-t`	Authentication token	-
`--wait`	`-w`	Wait for deployment	`true`
`--rollback`		Rollback on failure	`false`

Examples:

# Deploy to local runtime
pixell deploy

# Deploy to remote runtime
pixell deploy --runtime https://par.example.com

# Deploy specific package
pixell deploy --package ./releases/my-agent.apkg

`status` - Check Agent Status

Checks the status of deployed agents.

pixell status [options] [agent-id]

Arguments:

agent-id - Agent ID to check (optional)

Options:

Option	Short	Description	Default
`--runtime`	`-r`	PAR runtime URL	`http://localhost:8080`
`--token`	`-t`	Authentication token	-
`--format`	`-f`	Output format	`table`

Examples:

# Check all agents
pixell status

# Check specific agent
pixell status my-agent

# JSON output
pixell status --format json

`logs` - View Agent Logs

Views logs from deployed agents.

pixell logs [options] [agent-id]

Arguments:

agent-id - Agent ID to view logs for (optional)

Options:

Option	Short	Description	Default
`--runtime`	`-r`	PAR runtime URL	`http://localhost:8080`
`--token`	`-t`	Authentication token	-
`--follow`	`-f`	Follow log output	`false`
`--tail`	`-n`	Number of lines to show	`100`
`--level`	`-l`	Log level filter	`info`

Examples:

# View recent logs
pixell logs

# Follow logs
pixell logs --follow

# Filter by level
pixell logs --level error

`stop` - Stop Agent

Stops a running agent.

pixell stop [options] [agent-id]

Arguments:

agent-id - Agent ID to stop (optional)

Options:

Option	Short	Description	Default
`--runtime`	`-r`	PAR runtime URL	`http://localhost:8080`
`--token`	`-t`	Authentication token	-
`--force`	`-f`	Force stop	`false`

Examples:

# Stop all agents
pixell stop

# Stop specific agent
pixell stop my-agent

# Force stop
pixell stop --force

`restart` - Restart Agent

Restarts a running agent.

pixell restart [options] [agent-id]

Arguments:

agent-id - Agent ID to restart (optional)

Options:

Option	Short	Description	Default
`--runtime`	`-r`	PAR runtime URL	`http://localhost:8080`
`--token`	`-t`	Authentication token	-
`--wait`	`-w`	Wait for restart	`true`

Examples:

# Restart all agents
pixell restart

# Restart specific agent
pixell restart my-agent

`config` - Manage Configuration

Manages agent configuration.

pixell config <command> [options]

Subcommands:

get - Get configuration value
set - Set configuration value
list - List all configuration
reset - Reset configuration

Examples:

# Get configuration
pixell config get name

# Set configuration
pixell config set name "my-agent"

# List all configuration
pixell config list

# Reset configuration
pixell config reset

`deps` - Manage Dependencies

Manages agent dependencies.

pixell deps <command> [options]

Subcommands:

install - Install dependencies
update - Update dependencies
remove - Remove dependencies
list - List dependencies

Examples:

# Install dependencies
pixell deps install

# Update dependencies
pixell deps update

# Remove dependency
pixell deps remove fastapi

`template` - Manage Templates

Manages agent templates.

pixell template <command> [options]

Subcommands:

list - List available templates
create - Create new template
install - Install template
remove - Remove template

Examples:

# List templates
pixell template list

# Create template
pixell template create my-template

# Install template
pixell template install https://github.com/user/template

Configuration File

PAK uses a YAML configuration file (pixell.yaml) in the project root:

# pixell.yaml
name: my-agent
version: 1.0.0
description: My awesome agent
author: Your Name
email: your.email@example.com

# Agent configuration
agent:
  entry_point: src/main.py
  requirements:
    - fastapi>=0.68.0
    - uvicorn>=0.15.0
  
  # API configuration
  api:
    host: 0.0.0.0
    port: 8080
    cors_origins:
      - "*"
  
  # A2A configuration
  a2a:
    enabled: true
    port: 50051
  
  # UI configuration
  ui:
    enabled: true
    path: /ui
    static_dir: static

# Build configuration
build:
  target: production
  compress: true
  optimize: true
  exclude:
    - "*.pyc"
    - "__pycache__"
    - "*.log"

# Deployment configuration
deploy:
  runtime: http://localhost:8080
  token: ${DEPLOY_TOKEN}
  wait_timeout: 300

# Development configuration
dev:
  reload: true
  debug: false
  log_level: info
  env_file: .env

Environment Variables

PAK respects the following environment variables:

Variable	Description	Default
`PIXELL_CONFIG`	Path to config file	`./pixell.yaml`
`PIXELL_LOG_LEVEL`	Log level	`info`
`PIXELL_DEBUG`	Debug mode	`false`
`PIXELL_VERBOSE`	Verbose output	`false`
`PIXELL_QUIET`	Quiet mode	`false`
`PIXELL_RUNTIME`	Default runtime URL	`http://localhost:8080`
`PIXELL_TOKEN`	Default auth token	-

Exit Codes

PAK uses the following exit codes:

Code	Description
`0`	Success
`1`	General error
`2`	Configuration error
`3`	Build error
`4`	Deployment error
`5`	Validation error
`6`	Network error
`7`	Authentication error
`8`	Permission error

Examples

Complete Workflow

# 1. Initialize new agent
pixell init my-agent --template advanced

# 2. Navigate to project
cd my-agent

# 3. Install dependencies
pixell deps install

# 4. Run tests
pixell test

# 5. Validate configuration
pixell validate

# 6. Run in development
pixell run --debug

# 7. Build package
pixell build --compress

# 8. Deploy to runtime
pixell deploy --runtime https://par.example.com

# 9. Check status
pixell status

# 10. View logs
pixell logs --follow

CI/CD Pipeline

# Build and test
pixell build --target production
pixell test --coverage

# Deploy to staging
pixell deploy --runtime https://staging-par.example.com

# Run integration tests
pixell test --pattern integration

# Deploy to production
pixell deploy --runtime https://par.example.com

Troubleshooting

Common Issues

1. Build Failures

Problem: Build command fails Solutions:

Check Python version compatibility
Verify all dependencies are installed
Check for syntax errors in code
Ensure configuration is valid

2. Deployment Failures

Problem: Deploy command fails Solutions:

Verify runtime is accessible
Check authentication token
Ensure APKG file exists
Check network connectivity

3. Runtime Errors

Problem: Agent fails to start Solutions:

Check agent logs: pixell logs
Verify configuration
Check port availability
Review error messages

Debug Mode

Enable debug mode for detailed output:

pixell --debug <command>

Verbose Output

Enable verbose output for more information:

pixell --verbose <command>

Next Steps

After using PAK CLI:

PAR Configuration - Configure PAR runtime
Environment Variables - Set up environment
APKG Schema - Understand package format
Full Deployment Guide - Complete deployment

Ready to build agents? Check out PAR Configuration to configure your runtime!

Overview​

Global Options​

Commands​

init - Initialize New Agent​

build - Build Agent Package​

run - Run Agent Locally​

test - Run Tests​

validate - Validate Agent​

deploy - Deploy Agent​

status - Check Agent Status​

logs - View Agent Logs​

stop - Stop Agent​

restart - Restart Agent​

config - Manage Configuration​

deps - Manage Dependencies​

template - Manage Templates​

Configuration File​

Environment Variables​

Exit Codes​

Examples​

Complete Workflow​

CI/CD Pipeline​

Troubleshooting​

Common Issues​

1. Build Failures​

2. Deployment Failures​

3. Runtime Errors​

Debug Mode​

Verbose Output​

Next Steps​

Overview

Global Options

Commands

`init` - Initialize New Agent

`build` - Build Agent Package

`run` - Run Agent Locally

`test` - Run Tests

`validate` - Validate Agent

`deploy` - Deploy Agent

`status` - Check Agent Status

`logs` - View Agent Logs

`stop` - Stop Agent

`restart` - Restart Agent

`config` - Manage Configuration

`deps` - Manage Dependencies

`template` - Manage Templates

Configuration File

Environment Variables

Exit Codes

Examples

Complete Workflow

CI/CD Pipeline

Troubleshooting

Common Issues

1. Build Failures

2. Deployment Failures

3. Runtime Errors

Debug Mode

Verbose Output

Next Steps