Skip to content
AIOS

CLI Usage Simulation

The aios CLI prepares your workspace. It creates files, validates structure, and recommends next steps. It does not write PRDs, fill templates, implement code, or make architecture decisions.

This guide walks through two scenarios: starting a new project and adopting an existing one.

New Project Simulation

Section titled “New Project Simulation”

Step 1: Install AIOS

Section titled “Step 1: Install AIOS”
Terminal window
npm install -g @donihadimas/aios
aios --version

What this does: Installs the CLI globally. No project files are created yet.

Step 2: Create the project

Section titled “Step 2: Create the project”
Terminal window
aios init demo-project

What AIOS writes:

  • demo-project/docs/ - Product, architecture, ADR, task, review, and context folders
  • demo-project/.aios/ - Skills, templates, prompts, references, workflows, commands, integrations, config
  • demo-project/AGENTS.md - Agent routing instructions
  • demo-project/README.md - Project overview

Optional: If you select native skill delivery, AIOS also creates agent-specific folders:

  • demo-project/.agents/skills/ - For Codex or generic agents
  • demo-project/.qwen/skills/ - For Qwen Code
  • demo-project/.opencode/skills/ - For OpenCode
  • demo-project/.agent/skills/ - For Antigravity

What AIOS does not do: Does not install npm dependencies, does not create app code, does not choose a framework.

Step 3: Validate the setup

Section titled “Step 3: Validate the setup”
Terminal window
cd demo-project
aios validate

What this does: Checks that expected files exist. Prints OK or lists missing items.

Step 4: Ask what to do next

Section titled “Step 4: Ask what to do next”
Terminal window
aios next

What this does: Prints a recommendation like “Run product discovery with your AI agent.” This is read-only. No files are changed.

Step 5: Create document stubs

Section titled “Step 5: Create document stubs”
Terminal window
aios create feature "Habit reminders"
aios create adr "Use server date for completion"
aios create task "Implement habit API"
aios create review "Habit API"
aios create release "0.3.1"

What AIOS writes: Each command creates a Markdown stub file from a template:

  • Feature PRD in docs/product/features/
  • ADR in docs/adr/
  • Task in docs/tasks/
  • Review report in docs/reviews/
  • Release notes in docs/releases/

The exact filenames are generated by the CLI based on the command type, provided name, and existing numbered files where applicable.

What AIOS does not do: Does not fill the content. The stubs have headers and placeholder sections. Your AI agent or you fill them in.

Step 6: Inspect the config

Section titled “Step 6: Inspect the config”
Terminal window
aios config

What this does: Prints the resolved project config including mode, docsRoot, projectShape, and agent settings. Read-only.

Existing Project Adoption Simulation

Section titled “Existing Project Adoption Simulation”

Step 1: Navigate to your project

Section titled “Step 1: Navigate to your project”
Terminal window
cd my-existing-project

Step 2: Adopt AIOS

Section titled “Step 2: Adopt AIOS”
Terminal window
aios adopt

What AIOS writes:

  • docs/ - Adds missing documentation folders
  • .aios/ - Installs the local workflow kit
  • AGENTS.md - Adds agent routing instructions
  • README.md - Updates if missing

What AIOS does not do: Never overwrites existing files. If a file already exists, it is skipped.

Step 3: Validate

Section titled “Step 3: Validate”
Terminal window
aios validate

What this does: Checks the adopted structure. Reports any missing expected files.

Step 4: Check next step

Section titled “Step 4: Check next step”
Terminal window
aios next

What this does: Prints the recommended next action based on what files already exist in your project.

What the CLI Does and Does Not Do

Section titled “What the CLI Does and Does Not Do”
The CLI DoesThe CLI Does Not Do
Create project structureWrite application code
Install .aios/ workflow kitFill PRD or template content
Create document stubs from templatesRun an AI agent
Validate project structureInstall app dependencies
Recommend next stepsApply database migrations
Manage integration rulesDeploy or publish
Install skills to native agent foldersMake architecture decisions

After CLI Setup

Section titled “After CLI Setup”

Once the CLI has prepared your workspace, the next step is to open an AI coding agent and ask it to fill the document stubs. The agent reads the skills, templates, and prompts from .aios/ and follows the workflow.

See the AI Agent Simulation guide for what to ask your agent after CLI setup.

Section titled “Related Pages”