aiox install

Install AIOX framework in an existing project

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

Related Commands

• init - Create new AIOX project
• update - Update to latest version
• validate - Verify installation integrity
• uninstall - Remove AIOX from project