CLI Commands Reference

Complete reference for all AIOX CLI commands

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]

id · 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