CLI Reference

Complete command reference for AKIOS. All commands work with pip install, Docker wrapper, or direct Docker.

Quick Start Commands

The commands you'll use most:

akios init my-project          # Create new project
akios setup                    # Configure API keys
akios run templates/hello.yml  # Run a workflow
akios status                   # Check system status
akios logs --limit 10          # View recent logs
akios clean --old-runs         # Clean up old runs

Installation Methods

Choose your preferred installation:

Pip (Linux - Maximum Security)

pip install akios>=1.0.15
akios --version

Docker Wrapper (Cross-Platform)

curl -O https://raw.githubusercontent.com/akios-ai/akios/main/src/akios/cli/data/wrapper.sh
mv wrapper.sh akios
chmod +x akios
./akios --version

Direct Docker (Fallback)

docker run --rm -v "$(pwd):/app" -w /app akiosai/akios:v1.0.15 --version

Global Options

Available on all commands:

akios --help               # Show command help
akios --version            # Show version info
akios --debug <command>    # Enable debug output
akios --json-output <cmd>  # Machine-readable JSON output (v1.0.12+)

Project Commands

akios init [path]

Create a new AKIOS project with templates and configuration.

# Create project in current directory
akios init

# Create project in subdirectory
akios init my-project

# Create quietly (no banners)
akios init --quiet

# Initialize and run setup wizard immediately
akios init --wizard

Options:

• --force - Overwrite existing files
• --quiet - Suppress welcome message
• --json - Output in JSON format
• --wizard - Run the setup wizard after project initialization

Creates:

• config.yaml - Runtime configuration
• templates/ - Example workflows
• workflows/ - Your custom workflows
• data/input/ and data/output/ - File storage
• audit/ - Security logs
• .env and .env.example - API key configuration

akios setup [--force]

Interactive wizard to configure API keys and settings.

# Run setup wizard (first-time setup)
akios setup

# Force re-run (reconfigure everything)
akios setup --force

# Non-interactive mode (CI/CD)
akios setup --non-interactive

# Use defaults (quick setup)
akios setup --defaults

# Enable mock mode (no API keys needed)
akios setup --mock-mode

Configures:

• AI provider (OpenAI, Anthropic, Grok, Mistral, Gemini)
• API key with validation
• Budget limits ($1.00 default)
• Token limits (1000 per call default)
• Network access settings

akios status [options]

Show system status and security information.

# Basic status
akios status

# Detailed security dashboard
akios status --security

# Budget tracking details
akios status --budget

# Machine-readable JSON
akios status --json

# Detailed technical info
akios status --verbose

Shows:

• Security level (Full/Strong)
• PII protection status
• Budget usage and remaining
• Audit logging status
• Recent workflow runs

akios clean [options]

Remove old workflow runs to free disk space.

# Remove runs older than 7 days (default)
akios clean --old-runs

# Remove runs older than 30 days
akios clean --old-runs 30

# Preview what would be cleaned
akios clean --old-runs 7 --dry-run

# JSON output for scripts
akios clean --old-runs 7 --json

Safety: Only removes data/output/run_* directories. Audit logs are never touched.

Workflow Commands

akios run <workflow.yml> [options]

Execute a workflow with full security.

# Run a template
akios run templates/hello-workflow.yml

# Run your custom workflow
akios run workflows/my-workflow.yml

# Enable real API mode (interactive setup)
akios run workflow.yml --real-api

# Verbose output
akios run workflow.yml --verbose

# Dry run (validate only)
akios run workflow.yml --dry-run

# Skip confirmations
akios run workflow.yml --force

Options:

• --real-api - Enable live APIs with setup wizard
• --verbose, -v - Detailed execution logs
• --quiet, -q - Suppress banners
• --dry-run, -d - Validate without executing
• --force, -f - Skip confirmation prompts
• --debug - Enable debug logging

akios templates list

Show all available workflow templates.

akios templates list

Output:

Available Templates
===================
hello-workflow.yml        Simple AI greeting example
document_ingestion.yml    Document analysis with PII redaction
batch_processing.yml      Multi-file processing with cost tracking
file_analysis.yml         Security-focused file scanning

akios files [input|output]

Show available input files and output runs.

# Show all files
akios files

# Show only input files
akios files input

# Show only output runs
akios files output

Helps you see what data is available for your workflows.

Audit & Logging Commands

akios logs [options]

View workflow execution logs.

# Show recent logs (default 20 entries)
akios logs

# Show last 50 entries
akios logs --limit 50

# Show logs for specific workflow
akios logs --task workflow-123

# Filter by log level
akios logs --level ERROR

Options:

• --limit, -l - Number of entries to show
• --task, -t - Filter by workflow ID
• --level - Filter by level (INFO, ERROR, etc.)

akios audit export [options]

Export cryptographic audit trail.

# Export latest audit (auto-generated filename)
akios audit export

# Export with custom filename
akios audit export --output audit-report.json

# Export specific workflow
akios audit export --task workflow-123 --output audit.json

Options:

• --output, -o - Output file path
• --task, -t - Specific workflow ID
• --format, -f - Export format (json)

Advanced Commands

akios doctor [--json]

Run system diagnostics.

# Show diagnostics
akios doctor

# JSON output for scripts
akios doctor --json

Checks security status, configuration, and system health.

akios compliance report <workflow.yml> [options]

Generate compliance reports.

# Basic compliance report
akios compliance report hello-workflow.yml

# Detailed technical report
akios compliance report workflow.yml --type detailed

# Executive summary
akios compliance report workflow.yml --type executive --format txt

# Export to file
akios compliance report workflow.yml --output compliance.json

Report types:

• basic - Security validation summary
• detailed - Technical details + audit events
• executive - High-level management summary

akios output — Manage Workflow Outputs

Manage and organize workflow outputs with advanced file operations.

# Get the latest workflow output as deployable JSON
akios output latest

# List all workflow outputs
akios output list

# List outputs for specific workflow
akios output list hello-workflow.yml

# Clean old outputs for a workflow
akios output clean hello-workflow.yml --max-age 7

# Archive outputs for a workflow
akios output archive hello-workflow.yml --name archive.tar.gz

Subcommands:

latest

Retrieve the most recent workflow execution result as structured JSON — designed for CI/CD pipeline integration. The output includes metadata (version, workflow name, ID, timestamp), execution details (status, steps, timing), security state (PII, audit, sandbox), cost breakdown (total, budget, remaining), and per-step results.

list

List workflow outputs. Optionally filter by workflow name.

clean

Clean old workflow outputs. Options: --max-age (days, default 30), --max-count (default 50), --dry-run, --json.

archive

Archive workflow outputs. Options: --name (filename, auto-generated if omitted), --json.

akios cage / akios security — Security Cage Management

Manage the AKIOS security cage — control PII redaction, network access, sandboxing, and audit logging. cage and security are interchangeable aliases.

# Activate full security (PII redaction, HTTPS lock, sandbox, audit)
akios cage up

# Ablation flags — disable individual components for benchmarking
akios cage up --no-pii      # Skip PII redaction
akios cage up --no-audit    # Skip audit logging
akios cage up --no-budget   # Skip budget enforcement

# Relax security for development (destroys session data by default)
akios cage down

# Multi-pass secure erasure (DOD 5220.22-M)
akios cage down --passes 3

# Fast teardown (truncate-only, dev/CI)
akios cage down --fast

# Dev mode — relax protections, keep data for debugging
akios cage down --keep-data

# Full erasure including input data (v1.0.14+)
akios cage down --wipe-all

# Show current cage posture and protection status
akios cage status

# Same commands via 'security' alias
akios security up
akios security down
akios security status

cage up activates: PII Redaction (enabled), HTTPS Network (locked — LLM APIs and allowed_domains pass through), Sandbox (enforced), Audit Logging (enabled).

cage down (default) destroys session data — audit/ and data/output/ are permanently deleted. Since v1.0.14, data/input/ is preserved by default. Use --wipe-all to include input data in the erasure. Use --passes N for multi-pass overwrite (DOD 5220.22-M requires 3). Use --fast for truncate-only teardown in dev/CI environments.

cage down --keep-data relaxes protections without wiping data (development convenience only).

cage status displays current posture (ACTIVE / RELAXED / CUSTOM) and protection table.

akios protect — PII Protection Analysis

Analyze workflows and files for PII exposure before execution.

# Preview PII detection on a workflow
akios protect preview templates/hello-workflow.yml

# Scan a file for PII and show redaction results
akios protect scan data/input/document.txt

# JSON output for scripting
akios protect preview --json
akios protect scan data/input/document.txt --json

preview scans workflow inputs for PII and shows safe prompt construction.

scan scans a file for PII and displays detected sensitive data categories. Use --text to scan inline text without creating a file:

akios protect scan --text "Contact john@example.com or call 555-1234"

show-prompt displays the internal PII detection prompt template used by the redaction engine. Useful for auditing how PII matching is configured.

akios protect show-prompt

akios audit verify — Verify Audit Integrity

Verify the Merkle-chain integrity of the cryptographic audit trail.

akios audit verify
akios audit verify --json

Returns chain integrity status, hash verification results, and tamper detection.

akios audit log — View Audit Log

View recent entries from the cryptographic audit log.

akios audit log
akios audit log --limit 20

Options: --limit, -n (default 10), --json.

akios docs — View Documentation

View AKIOS documentation with Markdown rendering directly in the terminal.

akios docs
akios docs security
akios docs workflows

akios timeline — Workflow Timeline

View workflow execution timeline with performance analysis and step-by-step timing.

akios timeline
akios timeline --verbose
akios timeline --json

akios testing — Testing Context

View environment notes and testing context for the current project.

akios testing

Displays mock mode status, API key availability, and testing recommendations.

akios http — HTTP Agent

Direct HTTP agent for making rate-limited, PII-redacted HTTP requests within the security cage.

# Make a GET request
akios http GET https://api.example.com/data

# POST with data
akios http POST https://api.example.com/submit --data '{"key": "value"}'

Requires network_access_allowed: true and the target domain in allowed_domains. All requests are HTTPS-only, rate-limited (10 req/min), and PII-scanned.

akios workflow validate — Workflow Validation

Validate workflow YAML files against the schema without executing them.

# Validate a workflow file
akios workflow validate workflows/my-workflow.yml

# Validate with JSON output
akios workflow validate workflows/my-workflow.yml --json

Checks: valid YAML structure, required fields present, agent names exist, action names valid for each agent, parameter types correct, step references resolve.

akios audit rotate — Rotate Audit Log

Archive the current audit chain and start a fresh one.

akios audit rotate
akios audit rotate --json

The existing chain is moved to audit/archive/ with a timestamp. A new empty chain is initialized. Use this for long-running deployments to keep audit files manageable.

akios audit stats — Audit Statistics

Show aggregate statistics across the audit trail.

akios audit stats
akios audit stats --json

Displays: total entries, chain length, time span, entries per day, most common actions, PII detections count, and chain integrity status.

LLM Provider/Model Validation

AKIOS validates LLM provider and model compatibility at startup to prevent API failures.

Validation is case-insensitive. Invalid combinations fail early with clear error messages:

# Invalid — wrong provider for model
AKIOS_LLM_PROVIDER=openai AKIOS_LLM_MODEL=grok-3 akios status
# Error: "Model 'grok-3' is not valid for provider 'openai'"

Use AKIOS_JSON_MODE=1 for structured error output in CI/CD.

Environment Variables

Control AKIOS behavior with environment variables:

# Show JSON output
AKIOS_JSON_MODE=1 akios status

# Enable debug logging
AKIOS_DEBUG=1 akios run workflow.yml

# Set API provider
AKIOS_LLM_PROVIDER=grok akios status

# Enable mock mode
AKIOS_MOCK_LLM=1 akios run workflow.yml

Common Workflows

First-Time Setup

# 1. Install
pip install akios>=1.0.15

# 2. Create project
akios init my-project
cd my-project

# 3. Configure
akios setup

# 4. Run example
akios run templates/hello-workflow.yml

# 5. Check status
akios status

Daily Usage

# Run your workflow
akios run workflows/my-workflow.yml

# Check results
akios files output

# View logs
akios logs --limit 10

# Clean up periodically
akios clean --old-runs 7

Troubleshooting

# Check security status
akios status --security

# Enable debug mode
akios --debug run workflow.yml

# Run diagnostics
akios doctor

# View detailed logs
akios logs --limit 50 --level ERROR

Getting Help

# General help
akios --help

# Command-specific help
akios run --help
akios status --help
akios clean --help

# Show version
akios --version

Platform Differences

Native Linux (pip):

• Full kernel-hard security
• Best performance
• Maximum isolation
• Commands: akios <command>

Docker (all platforms):

• Strong policy-based security
• Cross-platform compatibility
• Container isolation
• Commands: ./akios <command> (from project directory)

Both methods provide the same commands and strong security.

Learn More

• Quickstart - Get started guide
• Concepts - How AKIOS works
• Configuration - Customize settings
• Debugging - Troubleshooting guide