aiox init

Create a new AIOX project with specified configuration

The aiox init command creates a new AIOX project in a specified directory with full framework setup.

Usage

npx aiox-core init <project-name> [options]

Arguments

project-name · string · required

Name of the project directory to create. Use . to install in the current directory.

npx aiox-core init my-project
npx aiox-core init .

Options

--force · flag

Force creation in a non-empty directory. Without this flag, init will fail if the target directory exists and contains files.

npx aiox-core init my-project --force

--skip-install · flag

Skip npm dependency installation during project creation. Useful for faster setup or custom dependency management.

npx aiox-core init my-project --skip-install

--template · string · default: "default"

Specify which template to use for project initialization.

Available templates:

• default - Full installation with all agents, tasks, and workflows
• minimal - Essential files only (dev agent + basic tasks)
• enterprise - Everything + dashboards + team integrations

npx aiox-core init my-project --template minimal
npx aiox-core init my-project -t enterprise

-t · string

Shorthand for --template.

npx aiox-core init my-project -t minimal

-h, --help · flag

Display help information for the init command.

npx aiox-core init --help

Examples

Create a New Project

Create a new project with default settings:

npx aiox-core init my-aiox-project

This will:

1. Create my-aiox-project/ directory
2. Initialize git repository
3. Create package.json
4. Run the installation wizard
5. Install framework files
6. Configure IDE settings

Minimal Project Setup

Create a lightweight project with essential components only:

npx aiox-core init my-project --template minimal

The minimal template includes:

• Development agent only
• Core tasks
• Basic configuration
• No pre-installed squads

Enterprise Project

Create a full-featured enterprise project:

npx aiox-core init enterprise-app --template enterprise

The enterprise template includes:

• All agents and tasks
• Dashboard integrations
• Team collaboration tools
• Advanced workflows

Install in Current Directory

Initialize AIOX in an existing project directory:

cd existing-project
npx aiox-core init .

Force Overwrite

Create a project even if the directory is not empty:

npx aiox-core init my-project --force

Using --force will overwrite existing files. Make sure you have backups or version control in place.

Skip Dependency Installation

Create project structure without installing npm dependencies:

npx aiox-core init my-project --skip-install
cd my-project
npm install  # Install dependencies later

Interactive Wizard

After running init, you’ll be guided through an interactive setup:

1. Installation Mode

Choose how you’re using AIOX:

• Using AIOX in a project - Framework files added to .gitignore
• Developing AIOX framework itself - Framework files are source code

2. Project Management Tool

Select your PM integration:

• None (local YAML files only) - Recommended
• ClickUp - Requires API token
• GitHub Projects - Uses gh auth
• Jira - Requires API token

3. IDE Selection

Choose which IDEs to configure (multiple selection):

• Claude Code (v4) - Recommended
• Cursor (v4)
• Gemini CLI (v4)
• GitHub Copilot (v4)
• AntiGravity (v4)

The wizard will:

• Check if CLI tools are installed
• Offer to install missing tools
• Configure IDE-specific files
• Set up agent commands and rules

4. Squad Selection

Optionally install pre-built squads:

• squad-creator
• data-engineering
• testing-automation
• And more…

What Gets Created

After running init, your project will contain:

my-project/
├── .aiox-core/              # Framework core files
│   ├── agents/
│   ├── tasks/
│   ├── templates/
│   └── workflows/
├── .claude/                 # Claude Code config (if selected)
│   ├── CLAUDE.md
│   └── commands/
├── .cursor/                 # Cursor config (if selected)
│   └── rules/
├── squads/                  # Squad definitions (if selected)
├── .aiox-installation-config.yaml
├── .gitignore
└── package.json

Exit Codes

• 0 - Project created successfully
• 1 - Project creation failed (e.g., directory exists, invalid template)

Troubleshooting

Directory Already Exists

If you see:

❌ Directory already exists and is not empty: my-project
Use --force to overwrite.

Use --force to proceed:

npx aiox-core init my-project --force

Invalid Template

If you see:

❌ Unknown template: custom
Available templates: default, minimal, enterprise

Use one of the supported templates:

npx aiox-core init my-project --template default

Missing Project Name

If you see:

❌ Project name is required

Provide a project name:

npx aiox-core init my-project

Next Steps

After creating your project:

1. Navigate to the project directory:

   cd my-project
   

2. Verify installation:

   aiox validate
   

3. Run system diagnostics:

   aiox doctor
   

4. Start using agents in your IDE based on your selection:

   • Claude Code: Use slash commands like /dev, /architect
   • Cursor: Use @agent-name in chat
   • GitHub Copilot: Select agent mode in Chat view

Related Commands

• install - Install AIOX in existing project
• validate - Verify installation integrity
• doctor - Run system diagnostics