Skip to main content
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
  • install - Install AIOX in existing project
  • validate - Verify installation integrity
  • doctor - Run system diagnostics

Build docs developers (and LLMs) love

Get started for freeTalk to us