Skip to main content
The aiox install command installs the AIOX framework in your current project directory, including all agents, tasks, templates, and IDE configurations.

​
Usage

npx aiox-core install [options]
Runs in the current directory. For creating a new project, use aiox init instead.

​
Options

​
--force
flag
Overwrite existing AIOX installation without prompting. Use this to reinstall or update manually.
npx aiox-core install --force
​
--quiet
flag
Minimal output with no banner or prompts. Ideal for CI/CD pipelines.
npx aiox-core install --quiet --force
​
--dry-run
flag
Simulate installation without modifying any files. Shows what would be installed.
npx aiox-core install --dry-run
​
--merge
flag
Automatically merge existing config files in brownfield installations. Preserves your customizations while adding new AIOX settings.Affects:
  • .env files - Adds new variables, preserves existing values
  • CLAUDE.md - Updates AIOX sections, keeps custom rules
npx aiox-core install --merge
​
--no-merge
flag
Disable automatic merging. Uses legacy overwrite behavior instead.
npx aiox-core install --no-merge
​
-h, --help
flag
Display help information for the install command.
npx aiox-core install --help

​
Examples

​
Basic Installation

Install AIOX in your current project with interactive prompts: 
cd my-project
npx aiox-core install
This will:
  1. Detect or initialize git repository
  2. Create package.json if missing
  3. Run the installation wizard
  4. Install framework files to .aiox-core/
  5. Configure selected IDEs
  6. Update .gitignore

​
Quiet Installation (CI/CD)

Install without any prompts or banners: 
npx aiox-core install --quiet --force
Perfect for:
  • CI/CD pipelines
  • Docker builds
  • Automated deployment scripts

​
Preview Installation

See what would be installed without making changes: 
npx aiox-core install --dry-run
Shows:
  • Files that would be created
  • IDE configurations to be installed
  • .gitignore changes

​
Force Reinstall

Reinstall AIOX, overwriting existing files: 
npx aiox-core install --force
Use cases:
  • Repair corrupted installation
  • Downgrade to specific version
  • Reset to default configuration
--force will overwrite customized framework files. Use --merge to preserve customizations.

​
Brownfield Installation (Smart Merge)

Install in a project with existing configs, preserving customizations: 
npx aiox-core install --merge
The smart merge:
  • Preserves your existing .env values
  • Adds new AIOX environment variables
  • Updates AIOX sections in CLAUDE.md
  • Keeps your custom IDE rules

​
Upgrade from Existing Installation

If AIOX is already installed, you’ll see an upgrade prompt: 
🔄 Existing AIOX installation detected!

   Upgrade available: 3.11.0 → 4.0.0

What would you like to do?
  ❯ Upgrade to 4.0.0 (12 new, 5 updated files)
    Dry Run (Show what would be changed)
    Fresh Install (Reinstall everything)
    Cancel (Exit without changes)

​
Upgrade Options

Upgrade - Smart upgrade that:
  • Installs new framework files
  • Updates modified framework files
  • Preserves user-modified files
  • Updates installation manifest
Dry Run - Preview changes: 
📦 Upgrade Report

New Files (12):
  ✓ .aiox-core/agents/squad-creator.md
  ✓ .aiox-core/tasks/create-squad.md
  ...

Updated Files (5):
  ✓ .aiox-core/agents/dev.md (v3.11.0 → v4.0.0)
  ...

User-Modified Files (2):
  ⚠ .aiox-core/agents/custom-agent.md (preserved)
  ...
Fresh Install - Complete reinstall:
  • Removes old installation
  • Installs all files fresh
  • Runs full wizard again

​
What Gets Installed

​
Framework Core

.aiox-core/
├── agents/           # 11 core agents
├── tasks/            # 68 tasks
├── templates/        # 23 templates
├── workflows/        # Workflow definitions
├── core/             # Core utilities
└── install-manifest.yaml

​
IDE Configurations

Based on your selection: Claude Code: 
.claude/
├── CLAUDE.md         # Main configuration
└── commands/
    └── AIOX/
        ├── agents/   # Agent slash commands
        └── tasks/    # Task definitions
Cursor: 
.cursor/
├── rules.md          # Main configuration
└── rules/
    └── AIOX/
        └── agents/   # Agent rules (.mdc files)
GitHub Copilot: 
.github/
└── chatmodes/        # Agent chat modes

​
Configuration Files

  • .aiox-installation-config.yaml - Installation metadata
  • .aiox-pm-config.yaml - Project management integration
  • .aiox-core/version.json - Version tracking
  • .aiox-core/.installed-manifest.yaml - File integrity tracking

​
Updated Files

  • .gitignore - Adds AIOX framework entries (project-development mode)
  • package.json - Initialized if missing

​
Interactive Wizard

The installation wizard guides you through:
  1. Installation Mode:
    • Using AIOX in a project (files added to .gitignore)
    • Developing AIOX framework (files are source code)
  2. PM Tool Integration:
    • None (local YAML)
    • ClickUp
    • GitHub Projects
    • Jira
  3. IDE Selection (multi-select):
    • Claude Code
    • Cursor
    • Gemini CLI
    • GitHub Copilot
    • AntiGravity
  4. CLI Tools Installation:
    • Detects missing CLI tools
    • Offers to install (e.g., @anthropic-ai/claude-code)
  5. Squad Selection (optional):
    • squad-creator
    • data-engineering
    • testing-automation
    • etc.

​
Post-Installation Validation

After installation, AIOX automatically:
  1. Validates file integrity
  2. Checks for missing files
  3. Verifies framework structure
  4. Creates installation manifest
If validation finds issues: 
aiox validate --repair

​
Exit Codes

  • 0 - Installation successful
  • 1 - Installation failed or cancelled

​
Troubleshooting

​
No Git Repository

AIOX will automatically initialize git: 
⚙️  Setting up project prerequisites...
✓ Git repository initialized

​
Missing package.json

AIOX creates a default package.json: 
✓ package.json created

​
Installation Validation Failed

If you see validation warnings: 
⚠ Installation validation found issues:
   - Missing files: 3
   - Corrupted files: 0

   Run aiox validate --repair to fix issues
Repair the installation: 
aiox validate --repair

​
Version Mismatch

If local and package versions differ: 
⚠️  Version mismatch!
  Local:  3.11.0
  Latest: 4.0.0
  Run 'npx aiox-core update' to update.
Update to latest: 
aiox update

​
Configuration Files

​
.aiox-installation-config.yaml

Stores installation metadata: 
installation:
  mode: project-development
  detected_at: 2024-03-05T10:30:00.000Z
repository:
  url: https://github.com/user/project
  auto_detect: true
framework:
  source: npm
  version: 4.0.0
  location: /path/to/aiox-core

​
.aiox-core/version.json

Tracks installation version: 
{
  "version": "4.0.0",
  "mode": "project-development",
  "installedAt": "2024-03-05T10:30:00.000Z",
  "fileHashes": { ... },
  "customized": []
}

​
Smart Merge (Brownfield)

When installing in projects with existing configs:

​
Environment Variables (.env)

Before: 
MY_API_KEY=secret123
DATABASE_URL=postgres://...
After --merge: 
MY_API_KEY=secret123
DATABASE_URL=postgres://...

# Added by AIOX
AIOX_MODE=production
AIOX_LOG_LEVEL=info

​
IDE Rules (CLAUDE.md)

Before: 
# My Custom Rules

- Always use TypeScript
- Write tests first
After --merge: 
# My Custom Rules

- Always use TypeScript
- Write tests first

# AIOX Framework Configuration
...

​
Next Steps

After installation:
  1. Validate installation: 
    aiox validate
  2. Run system diagnostics: 
    aiox doctor
  3. Check version: 
    aiox --version -d
  4. Explore installed agents: 
    ls .aiox-core/agents/
  5. Start using in your IDE:
    • Claude Code: /dev, /architect, /qa
    • Cursor: @dev, @architect
    • GitHub Copilot: Select agent mode
  • init - Create new AIOX project
  • update - Update to latest version
  • validate - Verify installation integrity
  • uninstall - Remove AIOX from project

Build docs developers (and LLMs) love

Get started for freeTalk to us