> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
npx aiox-core install [options]
```

Runs in the current directory. For creating a new project, use [`aiox init`](/cli/init) instead.

## Options

<ParamField path="--force" type="flag">
  Overwrite existing AIOX installation without prompting. Use this to reinstall or update manually.

  ```bash theme={null}
  npx aiox-core install --force
  ```
</ParamField>

<ParamField path="--quiet" type="flag">
  Minimal output with no banner or prompts. Ideal for CI/CD pipelines.

  ```bash theme={null}
  npx aiox-core install --quiet --force
  ```
</ParamField>

<ParamField path="--dry-run" type="flag">
  Simulate installation without modifying any files. Shows what would be installed.

  ```bash theme={null}
  npx aiox-core install --dry-run
  ```
</ParamField>

<ParamField path="--merge" type="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

  ```bash theme={null}
  npx aiox-core install --merge
  ```
</ParamField>

<ParamField path="--no-merge" type="flag">
  Disable automatic merging. Uses legacy overwrite behavior instead.

  ```bash theme={null}
  npx aiox-core install --no-merge
  ```
</ParamField>

<ParamField path="-h, --help" type="flag">
  Display help information for the install command.

  ```bash theme={null}
  npx aiox-core install --help
  ```
</ParamField>

## Examples

### Basic Installation

Install AIOX in your current project with interactive prompts:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
npx aiox-core install --force
```

Use cases:

* Repair corrupted installation
* Downgrade to specific version
* Reset to default configuration

<Warning>
  `--force` will overwrite customized framework files. Use `--merge` to preserve customizations.
</Warning>

### Brownfield Installation (Smart Merge)

Install in a project with existing configs, preserving customizations:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
aiox update
```

## Configuration Files

### .aiox-installation-config.yaml

Stores installation metadata:

```yaml theme={null}
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:

```json theme={null}
{
  "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**:

```bash theme={null}
MY_API_KEY=secret123
DATABASE_URL=postgres://...
```

**After `--merge`**:

```bash theme={null}
MY_API_KEY=secret123
DATABASE_URL=postgres://...

# Added by AIOX
AIOX_MODE=production
AIOX_LOG_LEVEL=info
```

### IDE Rules (CLAUDE.md)

**Before**:

```markdown theme={null}
# My Custom Rules

- Always use TypeScript
- Write tests first
```

**After `--merge`**:

```markdown theme={null}
# My Custom Rules

- Always use TypeScript
- Write tests first

# AIOX Framework Configuration
...
```

## Next Steps

After installation:

1. **Validate installation**:
   ```bash theme={null}
   aiox validate
   ```

2. **Run system diagnostics**:
   ```bash theme={null}
   aiox doctor
   ```

3. **Check version**:
   ```bash theme={null}
   aiox --version -d
   ```

4. **Explore installed agents**:
   ```bash theme={null}
   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](/cli/init) - Create new AIOX project
* [update](/cli/commands#update) - Update to latest version
* [validate](/cli/commands#validate) - Verify installation integrity
* [uninstall](/cli/commands#uninstall) - Remove AIOX from project