CLI Overview

AIOX CLI architecture, command structure, and global options

The AIOX CLI provides a comprehensive command-line interface for managing AIOX installations, running diagnostics, and working with the framework.

Command Structure

The AIOX CLI follows a hierarchical command structure:

aiox [command] [subcommand] [options]

Main Entry Points

Primary CLI: npx aiox-core or aiox (if installed globally)

• Installation and project management commands
• System diagnostics and information
• Framework updates and validation

Modular CLI: aiox <category> (requires local installation)

• Workers discovery (aiox workers)
• Configuration management (aiox config)
• Quality gates (aiox qa)
• Metrics tracking (aiox metrics)
• Pro features (aiox pro)

Global Options

These options are available across most commands:

--version · flag

Display the installed version of AIOX

npx aiox-core --version

--version -d · flag

Display detailed version information including installation metadata

npx aiox-core --version -d

Shows:

• Package version
• Installation mode (project-development or framework-development)
• Installed and updated timestamps
• File count and customization status
• Version comparison with latest

--help · flag

Display help information for any command

npx aiox-core --help
aiox workers --help
aiox config show --help

-v, --verbose · flag

Enable verbose output for detailed logging (command-specific)

aiox update --verbose
aiox validate --verbose

--json · flag

Output results in JSON format for CI/CD integration (command-specific)

aiox validate --json
aiox doctor --json

Exit Codes

The CLI uses consistent exit codes across commands:

• 0: Success - command completed successfully
• 1: Validation/check failed - issues detected (run with --fix if available)
• 2: Error - command could not complete due to an error

CLI Architecture

Standalone Entry Point

The main CLI (bin/aiox.js) is standalone with no external dependencies for npx compatibility. This ensures:

• Fast execution for common commands
• Works even if node_modules is not installed
• Minimal overhead for simple operations

Modular Commands

Advanced commands are modular and loaded from .aiox-core/cli/:

• Workers discovery
• Configuration management
• Quality gates
• Metrics tracking
• Pro license features

These require a local AIOX installation.

Common Patterns

Dry Run Mode

Many commands support --dry-run to preview changes:

aiox install --dry-run
aiox validate --repair --dry-run
aiox update --dry-run
aiox config migrate --dry-run

Force Mode

Use --force to bypass confirmation prompts:

aiox install --force
aiox uninstall --force
aiox update --force

Quiet Mode

Minimize output with --quiet (ideal for CI/CD):

aiox install --quiet --force
aiox doctor --quiet

Getting Help

For detailed help on any command:

# General help
aiox --help

# Command-specific help
aiox init --help
aiox install --help
aiox validate --help

# Subcommand help
aiox config --help
aiox config show --help
aiox workers search --help

Configuration Files

The CLI interacts with several configuration files:

• .aiox-installation-config.yaml - Installation metadata
• .aiox-core/version.json - Version tracking for updates
• .aiox-core/install-manifest.yaml - File integrity manifest
• .aiox-core/framework-config.yaml - Framework configuration (L1)
• .aiox-core/project-config.yaml - Project configuration (L2)
• .aiox-core/local-config.yaml - Local overrides (L4)

Next Steps

• init command - Create new AIOX projects
• install command - Install AIOX in existing projects
• All commands reference - Complete command reference