CLI Commands Reference

Comprehensive reference for all AIOX CLI commands beyond init and install.

System Commands

doctor

Run health checks on your AIOX installation.

aiox doctor [options]

--fix

flag

Automatically fix detected issues.

aiox doctor --fix

--dry-run

flag

Show what --fix would do without making changes.

aiox doctor --fix --dry-run

--json

flag

Output results as structured JSON.

aiox doctor --json

--quiet

flag

Minimal output (exit code only).

aiox doctor --quiet

Checks performed:

Required directories exist (.aiox-core/, .aiox/)
Configuration files are valid JSON/YAML
Agent definitions are complete
Task files have required fields
Dependencies are installed

Exit codes:

0 - All checks passed (or issues fixed with --fix)
1 - Issues detected (run with --fix to repair)

Examples:

# Run health check
aiox doctor

# Auto-fix detected issues
aiox doctor --fix

# Preview what would be fixed
aiox doctor --fix --dry-run

info

Show system information about your AIOX installation.

aiox info

Displays:

AIOX version
Platform and Node.js version
Architecture
Working directory
Install location
Component counts (agents, tasks, templates, workflows)
AIOX Pro license status (if installed)

Example output:

📊 AIOX-FullStack System Information

Version: 4.0.0
Platform: linux
Node.js: v20.11.0
Architecture: x64
Working Directory: /home/user/project
Install Location: /home/user/.npm/_npx/aiox-core

✓ AIOX Core installed
  - Agents: 11
  - Tasks: 68
  - Templates: 23
  - Workflows: 15

✓ AIOX Pro installed
  - License: ✅ Active
  - Features: 12 available

validate

Validate AIOX-Core installation integrity.

aiox validate [options]

--repair

flag

Repair missing or corrupted files.

aiox validate --repair

--dry-run

flag

Preview repairs without applying (use with --repair).

aiox validate --repair --dry-run

--detailed

flag

Show detailed file list.

aiox validate --detailed

--no-hash

flag

Skip hash verification (faster validation).

aiox validate --no-hash

--extras

flag

Detect extra files not in manifest.

aiox validate --extras

--json

flag

Output results as JSON for CI/CD.

aiox validate --json

--source

string

Source directory for repairs.

aiox validate --repair --source /path/to/aiox-core

Exit codes:

0 - Validation passed
1 - Validation failed (missing/corrupted files)
2 - Validation error (could not complete)

Examples:

# Validate current installation
aiox validate

# Validate with detailed file list
aiox validate --detailed

# Repair missing/corrupted files
aiox validate --repair

# Preview what would be repaired
aiox validate --repair --dry-run

# Quick validation (skip hash check)
aiox validate --no-hash

# Output as JSON for CI/CD
aiox validate --json

update

Update AIOX to the latest version.

aiox update [options]

--check

flag

Check for updates without applying.

aiox update --check

--dry-run

flag

Preview what would be updated.

aiox update --dry-run

--force

flag

Force update even if already up-to-date.

aiox update --force

--verbose

flag

Show detailed output during update.

aiox update --verbose

Examples:

# Update to latest version
aiox update

# Check for updates without applying
aiox update --check

# Preview what would be updated
aiox update --dry-run

# Force update even if up-to-date
aiox update --force

# Show detailed output
aiox update --verbose

uninstall

Remove AIOX from the current project.

aiox uninstall [options]

--force

flag

Skip confirmation prompt.

aiox uninstall --force

--keep-data

flag

Keep .aiox/ directory (settings and history).

aiox uninstall --keep-data

--dry-run

flag

Show what would be removed without removing.

aiox uninstall --dry-run

What gets removed:

.aiox-core/ - Framework core files
docs/stories/ - Story files (if created by AIOX)
squads/ - Squad definitions
.gitignore - AIOX-added entries only

What is preserved (with --keep-data):

.aiox/ - Project settings and agent history

Exit codes:

0 - Uninstall successful
1 - Uninstall failed or cancelled

Examples:

# Interactive uninstall (with confirmation)
aiox uninstall

# Force uninstall without prompts
aiox uninstall --force

# See what would be removed
aiox uninstall --dry-run

# Uninstall but keep project data
aiox uninstall --keep-data

Configuration Commands

config show

Show resolved configuration from layered config files.

aiox config show [options]

--level

string

Show specific level (1, 2, pro, 3, 4) without merging.

aiox config show --level 2

--app

string

Include app-specific config (L3).

aiox config show --app my-app

--debug

flag

Show source annotations for each value.

aiox config show --debug

Examples:

# Show full resolved config
aiox config show

# Show only framework config (L1)
aiox config show --level 1

# Show with source annotations
aiox config show --debug

config diff

Compare configuration between two levels.

aiox config diff --levels <a>,<b> [options]

--levels

string

required

Two levels to compare (e.g., “1,2” or “framework,project”).

aiox config diff --levels 1,2

--app

string

Include app-specific context.

aiox config diff --levels 1,2 --app my-app

Examples:

# Compare framework and project configs
aiox config diff --levels 1,2

# Compare project and local configs
aiox config diff --levels project,local

config migrate

Migrate monolithic core-config.yaml to layered files.

aiox config migrate [options]

--dry-run

flag

Preview without writing files.

aiox config migrate --dry-run

--force

flag

Overwrite existing split files.

aiox config migrate --force

Examples:

# Preview migration
aiox config migrate --dry-run

# Perform migration
aiox config migrate

# Force overwrite existing files
aiox config migrate --force

config validate

Validate YAML syntax and lint config files.

aiox config validate [options]

--level

string

Validate specific level only.

aiox config validate --level 2

Examples:

# Validate all config levels
aiox config validate

# Validate only project config
aiox config validate --level project

config init-local

Create local-config.yaml from template.

aiox config init-local

Creates .aiox-core/local-config.yaml from .aiox-core/local-config.yaml.template and updates .gitignore.

Workers Discovery

workers search

Search for workers matching a query.

aiox workers search <query> [options]

query

string

required

Search query (supports multi-word queries).

aiox workers search "json transformation"

--category

string

Filter by category.

aiox workers search "transform" --category=data

--tags

string

Filter by tags (comma-separated).

aiox workers search "api" --tags=rest,graphql

--format

string

Output format (table, json).

aiox workers search "json" --format=json

Examples:

# Search for workers
aiox workers search "json transformation"

# Search with category filter
aiox workers search "data" --category=etl

# Search with tags
aiox workers search "transform" --tags=etl,data

# JSON output
aiox workers search "api" --format=json

workers list

List all workers grouped by category.

aiox workers list [options]

--category

string

Filter by category.

aiox workers list --category=testing

--format

string

Output format (table, json).

aiox workers list --format=table

--page

number

Page number for pagination.

aiox workers list --page=2

Examples:

# List all workers
aiox workers list

# List workers in testing category
aiox workers list --category=testing

# Table format with pagination
aiox workers list --format=table --page=2

workers info

Show detailed information about a worker.

aiox workers info <id> [options]

string

required

Worker ID.

aiox workers info json-csv-transformer

--format

string

Output format (json, yaml).

aiox workers info architect-checklist --format=json

Examples:

# Show worker details
aiox workers info json-csv-transformer

# JSON output
aiox workers info architect-checklist --format=json

Pro Features

pro activate

Activate AIOX Pro license.

aiox pro activate --key <license-key>

pro status

Show AIOX Pro license status.

aiox pro status

pro deactivate

Deactivate AIOX Pro license.

aiox pro deactivate

pro features

List available Pro features.

aiox pro features

Version Information

—version

Show installed version.

aiox --version

Output:

4.0.0

—version -d

Show detailed version information.

aiox --version -d

Output:

AIOX-FullStack v4.0.0
Package: aiox-core

📦 Local Installation:
  Version:    4.0.0
  Mode:       project-development
  Installed:  3/5/2024
  Updated:    3/5/2024
  Files:      150 tracked
  Customized: 0 files

✅ Up to date

Exit Codes

Consistent exit codes across all commands:

0 - Success
1 - Validation/check failed
2 - Error (command could not complete)

Global Help

Get help for any command:

aiox --help
aiox <command> --help
aiox <command> <subcommand> --help

Examples:

aiox --help
aiox config --help
aiox config show --help
aiox workers search --help

Get Started

Core Concepts

Agents

CLI Reference

Workflows

Advanced

CLI Commands Reference

System Commands

doctor

info

validate

update

uninstall

Configuration Commands

config show

config diff

config migrate

config validate

config init-local

Workers Discovery

workers search

workers list

workers info

Pro Features

pro activate

pro status

pro deactivate

pro features

Version Information

—version

—version -d

Exit Codes

Global Help

Build docs developers (and LLMs) love

Get Started

Core Concepts

Agents

CLI Reference

Workflows

Advanced

​System Commands

​doctor

​info

​validate

​update

​uninstall

​Configuration Commands

​config show

​config diff

​config migrate

​config validate

​config init-local

​Workers Discovery

​workers search

​workers list

​workers info

​Pro Features

​pro activate

​pro status

​pro deactivate

​pro features

​Version Information

​—version

​—version -d

​Exit Codes

​Global Help

Build docs developers (and LLMs) love

System Commands

doctor

info

validate

update

uninstall

Configuration Commands

config show

config diff

config migrate

config validate

config init-local

Workers Discovery

workers search

workers list

workers info

Pro Features

pro activate

pro status

pro deactivate

pro features

Version Information

—version

—version -d

Exit Codes

Global Help