CLI Commands

Complete reference for all aibox commands.

Global Options

These options apply to all commands:

Option	Environment Variable	Default	Description
`--config <PATH>`	--	`./aibox.toml`	Path to configuration file
`--log-level <LEVEL>`	`AIBOX_LOG_LEVEL`	`info`	Log verbosity: `trace`, `debug`, `info`, `warn`, `error`

aibox init

Initialize a new project with aibox.toml and generated devcontainer files.

Usage

aibox init [OPTIONS]

Options

Option	Default	Description
`--name <NAME>`	Current directory name	Project and container name
`--base <BASE>`	`debian`	Base image: `debian`
`--process <PACKAGES>`	`core`	Process packages (space-separated): package names or presets
`--ai <PROVIDER>`	`claude`	AI provider(s): `claude`, `aider`, `gemini`, `mistral` (can be repeated)
`--theme <THEME>`	`gruvbox-dark`	Color theme: `gruvbox-dark`, `catppuccin-mocha`, `catppuccin-latte`, `dracula`, `tokyo-night`, `nord`, `projectious`
`--user <USER>`	`aibox`	Container user
`--addons <NAME>`	--	Addon names (can be repeated): `python`, `rust`, `node`, `go`, `latex`, `typst`, `infrastructure`, `kubernetes`, `cloud-aws`, etc.

What It Does

Creates aibox.toml with the specified settings
Creates .aibox-home/ directory with default configuration files
Generates .devcontainer/Dockerfile, docker-compose.yml, and devcontainer.json
Scaffolds context files based on the chosen process flavor
Updates .gitignore with required entries (.aibox-home/, .devcontainer/, etc.)

Examples

# Basic initialization (uses directory name, defaults)
aibox init

# Specify project name and process
aibox init --name my-api --process managed

# With addons
aibox init --name my-app --addons python --addons infrastructure

# Configure multiple AI providers
aibox init --ai claude --ai aider

# Choose a color theme
aibox init --name my-app --theme catppuccin-mocha

Exit Codes

Code	Meaning
0	Success
1	`aibox.toml` already exists, or invalid option value

Interactive Mode

When --name or --process flags are omitted and the terminal is interactive, aibox init prompts for each missing value.

The --process prompt shows only the four convenience presets (managed, software, research-project, full-product). To use an individual package instead, pass --process <name> explicitly on the command line.

In non-interactive environments (scripts, CI pipelines), omitted flags silently use defaults: the current directory name for --name, debian for --base, and core for --process.

!!! warning "Will not overwrite" If aibox.toml already exists, init exits with an error. Delete the file first or edit it directly.

aibox sync

Reconcile project state with aibox.toml. The single command for applying any config change.

Usage

aibox sync [OPTIONS]

Options

Option	Description
`--no-cache`	Build the container image without using the layer cache

What It Does

Checks for version migrations (schema updates between versions)
Force-updates theme-dependent config files in .aibox-home/
Seeds .aibox-home/ directory with default configs (if missing)
Regenerates .devcontainer/ files from aibox.toml
Reconciles skills — deploys missing skills, reports orphans
Generates AIBOX.md — universal agent baseline document
Builds the container image via docker compose build (skipped gracefully if no runtime)

Only files whose content has actually changed are written. Reports what was updated.

Examples

# After any config change
aibox sync

# Force full image rebuild
aibox sync --no-cache

Exit Codes

Code	Meaning
0	Success
1	No `aibox.toml` found, or invalid config

!!! note "generate is an alias" aibox generate still works as an alias for sync. New projects should use sync.

aibox start

Start the container and attach via Zellij.

Usage

aibox start [OPTIONS]

Options

Option	Default	Description
`--layout <LAYOUT>`	`dev`	Zellij layout: `dev`, `focus`, or `cowork`

What It Does

This is the primary command for daily use. It handles the full lifecycle:

Seeds .aibox-home/ directory with default configs (first run only)
Generates devcontainer files from aibox.toml
Checks container state:
- Running: Skips to attach
- Stopped: Starts the existing container
- Missing: Builds the image (if needed) and creates the container
Waits for the container to be ready (up to 7.5 seconds)
Attaches via zellij --layout <LAYOUT>

Available Layouts

Layout	Description
`dev`	Yazi (40%) + Vim (60%) side by side (default)
`focus`	One tool per tab, fullscreen
`cowork`	Yazi+Vim left, Claude right — side-by-side AI collaboration

All layouts include shared tabs for git (lazygit) and shell (extra bash).

Examples

# Start working with default layout
aibox start

# Start with focus layout (one tool per tab)
aibox start --layout focus

# Start with cowork layout (side-by-side with Claude)
aibox start --layout cowork

Exit Codes

Code	Meaning
0	Success (after Zellij session ends)
1	Config error, runtime not found, container failed to start

aibox stop

Stop the running container.

Usage

aibox stop

What It Does

Stops the container via docker compose stop (or podman compose stop). All data in .aibox-home/ and the workspace is preserved. The container can be restarted with aibox start.

Examples

aibox stop

Exit Codes

Code	Meaning
0	Container stopped, or was already stopped/missing
1	Config error or runtime not found

aibox remove

Stop and remove the container entirely.

Usage

aibox remove

What It Does

Unlike stop, this removes the container entirely (like docker rm). Use before switching to VS Code or when you want a clean slate. The container is stopped first if running, then removed.

All data in .aibox-home/ and the workspace is preserved -- only the container itself is deleted.

Aliases

aibox rm is a shorthand alias for aibox remove.

Examples

aibox remove
aibox rm

Exit Codes

Code	Meaning
0	Container removed, or was already missing
1	Config error or runtime not found

aibox status

Show the current container state.

Usage

aibox status

What It Does

Inspects the container and reports one of three states:

Running -- container is active
Stopped -- container exists but is not running
Missing -- no container found with the configured name

Examples

aibox status

Output:

 ✓ Container 'my-app' is running

Exit Codes

Code	Meaning
0	Status retrieved successfully (regardless of container state)
1	Config error or runtime not found

aibox doctor

Validate project structure and run diagnostics.

Usage

aibox doctor

What It Does

Validates aibox.toml (syntax, field values, semver versions)
Detects the container runtime
Checks for .aibox-home/ directory (suggests renaming .root/ if found for backward compatibility)
Checks for .devcontainer/ directory
Validates .gitignore contains required entries (.aibox-home/, .devcontainer/)
Validates mount source paths exist on the host
Reports image flavor, process flavor, and container name
Compares schema versions for migration needs

Examples

aibox doctor

Output:

==> Running diagnostics...
 ✓ Config version: 0.8.0
 ✓ Image: python
 ✓ Process: product
 ✓ Container name: my-app
 ✓ Container runtime: podman
 ✓ .aibox-home/ directory exists
 ✓ .devcontainer/ directory exists
 ✓ .gitignore contains required entries
 ✓ Mount source paths exist
 ✓ Diagnostics complete

Exit Codes

Code	Meaning
0	All checks passed
1	Config error or critical issue detected

aibox completions

Generate shell completion scripts for bash, zsh, fish, powershell, or elvish.

Usage

aibox completions <SHELL>

Where <SHELL> is one of: bash, zsh, fish, powershell, elvish.

Examples

aibox completions bash
aibox completions zsh
aibox completions fish

Setup

Add to your shell profile for persistent completions:

Bash (~/.bashrc):

eval "$(aibox completions bash)"

Zsh (~/.zshrc):

eval "$(aibox completions zsh)"

Fish (~/.config/fish/config.fish):

aibox completions fish | source

Exit Codes

Code	Meaning
0	Success
1	Unknown shell name

aibox env

Manage named environments for switching between configurations within a single project.

Environments save aibox.toml, CLAUDE.md, and context/ (excluding context/shared/) to .aibox-env/<name>/. Files in context/shared/ are shared across all environments.

Subcommands

aibox env create

Save the current project state as a named environment.

aibox env create <name>

Creates a snapshot of aibox.toml, CLAUDE.md, and context/ (excluding context/shared/) in .aibox-env/<name>/.

aibox env switch

Switch to a different environment.

aibox env switch <name> [--yes]

Stops any running container
Saves the current environment
Restores the target environment
Regenerates .devcontainer/ files

Requires confirmation (type switch). Use --yes to skip.

aibox env list

List available environments and show which is current.

aibox env list

aibox env delete

Delete a saved environment.

aibox env delete <name> [--yes]

Requires confirmation (type the environment name). Use --yes to skip.

aibox env status

Show current environment name and config summary.

aibox env status

Examples

# Create two environments from different configurations
aibox env create research
# ... edit aibox.toml to change image/process ...
aibox env create product

# Switch between them
aibox env switch research
aibox env switch product

# List environments
aibox env list

# Delete an environment
aibox env delete research --yes

Shared Files

Files in context/shared/ are not copied during environment switches — they stay in place and are shared across all environments. By default, OWNER.md is placed in context/shared/. Move any file there to share it across environments.

Exit Codes

Code	Meaning
0	Success
1	Environment not found, name invalid, or config error

aibox backup

Back up aibox files to a timestamped directory.

Usage

aibox backup [OPTIONS]

Options

Option	Default	Description
`--output-dir <DIR>`	`.aibox-backup/`	Output directory for backup
`--dry-run`	--	Preview what would be backed up without copying

What It Does

Copies all aibox managed files to a timestamped subdirectory:

aibox.toml
.devcontainer/
.aibox-home/
.aibox-version
context/
CLAUDE.md
.gitignore

The backup directory is named aibox-<version>-backup-<date>-<time> (e.g., aibox-0.8.0-backup-2026-03-22-1430).

Examples

# Back up current state
aibox backup

# Preview without copying
aibox backup --dry-run

# Back up to a custom directory
aibox backup --output-dir /tmp/my-backup

Exit Codes

Code	Meaning
0	Success
1	Config error or no files found

aibox reset

Remove all aibox files and reset the project to its pre-init state.

!!! danger "Danger zone" This command deletes aibox.toml, .devcontainer/, .aibox-home/, context/, CLAUDE.md, and .aibox-version. By default a backup is created first. .gitignore is backed up but not deleted.

Usage

aibox reset [OPTIONS]

Options

Option	Description
`--no-backup`	Skip backup — permanently delete without saving
`--dry-run`	Preview what would happen without modifying anything
`--yes`	Skip confirmation prompt

What It Does

Displays a table of files showing backup and deletion status
Prompts for confirmation (type reset or DELETE with --no-backup)
Stops any running container
Creates a backup (unless --no-backup)
Deletes all aibox files except .gitignore

Examples

# Reset with backup (safe default)
aibox reset

# Preview what would happen
aibox reset --dry-run

# Delete without backup (requires typing "DELETE" to confirm)
aibox reset --no-backup

# Non-interactive reset with backup
aibox reset --yes

Exit Codes

Code	Meaning
0	Success or user aborted
1	Config error or deletion failed

aibox update

Check for or apply updates.

Usage

aibox update [OPTIONS]

Options

Option	Description
`--check`	Only check for updates, do not apply
`--dry-run`	Preview what would change without writing files

What It Does

Checks the current version against the latest available release. Without flags, upgrades the image version in aibox.toml and regenerates container files.

--check — Queries GHCR for the latest image tag and GitHub Releases for the latest CLI version. Reports whether updates are available without changing anything.
No flags — Fetches the latest image version, updates version in aibox.toml, regenerates .devcontainer/ files, and updates .aibox-version. You still need to rebuild the container to apply changes.
--dry-run — Shows what would change without writing any files.

If the registry is unreachable or returns an authentication error, aibox update prints a warning and exits cleanly (exit code 0) rather than failing. Run docker login ghcr.io if you receive repeated authentication errors.

Examples

# Check for updates (read-only)
aibox update --check

# Preview upgrade without applying
aibox update --dry-run

# Upgrade image version and regenerate files
aibox update

Exit Codes

Code	Meaning
0	Success
1	Config error

aibox addon

Manage add-ons (language runtimes, tools, AI agents).

Subcommands

aibox addon list

List all available add-ons and their install status.

aibox addon list

Shows each add-on's name, tool count, and whether it's installed in the current project.

aibox addon add

Add an add-on to aibox.toml and run sync.

aibox addon add <name>

Inserts [addons.<name>.tools] with default-enabled tools into aibox.toml, then runs a full sync (regenerates files and rebuilds the image).

aibox addon remove

Remove an add-on from aibox.toml and run sync.

aibox addon remove <name>

aibox addon info

Show detailed info about an add-on: tools, supported versions, and defaults.

aibox addon info <name>

Examples

# See what's available
aibox addon list

# Add Python runtime
aibox addon add python

# Add Kubernetes tools
aibox addon add kubernetes

# Check what's in an add-on
aibox addon info rust

# Remove an add-on
aibox addon remove python

aibox skill

Manage skills (AI agent capabilities).

Subcommands

aibox skill list

List all available skills and their deploy status.

aibox skill list

Shows each skill's name, source package, and whether it's active in the current project.

aibox skill add

Add a skill to [skills].include in aibox.toml.

aibox skill add <name>

If the skill was in [skills].exclude, it's removed from there. Runs skill reconciliation after.

aibox skill remove

Remove a skill by managing [skills].include and [skills].exclude.

aibox skill remove <name>

If the skill was in [skills].include, removes it. Otherwise, adds it to [skills].exclude. Core skills (agent-management, owner-profile) cannot be removed.

aibox skill info

Show info about a skill, including a preview of its SKILL.md content.

aibox skill info <name>

Examples

# See all skills and their status
aibox skill list

# Add a skill not in your process packages
aibox skill add data-science

# Remove a skill from your active set
aibox skill remove debugging

# Preview a skill's content
aibox skill info code-review

aibox audio

Host-side audio diagnostics and setup for PulseAudio over TCP.

Subcommands

aibox audio check

Check if the host is correctly configured for container audio.

aibox audio check [--port <PORT>]

Runs diagnostics:

PulseAudio installation and version
Daemon status
TCP module (module-native-protocol-tcp) loaded on the expected port
Persistent configuration in default.pa
Port listening
macOS launchd agent status
TCP connectivity test

aibox audio setup

Automatically install and configure PulseAudio on the host.

aibox audio setup [--port <PORT>]

On macOS:

Installs PulseAudio via Homebrew (if not present)
Configures ~/.config/pulse/default.pa with the TCP module
Creates a launchd agent (com.aibox.pulseaudio) with KeepAlive for auto-start
Loads the service immediately
Runs audio check to verify

On Linux, prints manual setup instructions with the correct auth-ip-acl settings.

Options

Option	Default	Description
`--port <PORT>`	`4714`	PulseAudio TCP port

Examples

# Diagnose audio issues
aibox audio check

# Full automated setup (macOS)
aibox audio setup

# Use a custom port
aibox audio setup --port 4715

Exit Codes

Code	Meaning
0	Success (check passed or setup completed)
1	Setup failed (e.g., brew install failed)

Global Options​

aibox init​

Usage​

Options​

What It Does​

Examples​

Exit Codes​

Interactive Mode​

aibox sync​

Usage​

Options​

What It Does​

Examples​

Exit Codes​

aibox start​

Usage​

Options​

What It Does​

Available Layouts​

Examples​

Exit Codes​

aibox stop​

Usage​

What It Does​

Examples​

Exit Codes​

aibox remove​

Usage​

What It Does​

Aliases​

Examples​

Exit Codes​

aibox status​

Usage​

What It Does​

Examples​

Exit Codes​

aibox doctor​

Usage​

What It Does​

Examples​

Exit Codes​

aibox completions​

Usage​

Examples​

Setup​

Exit Codes​

aibox env​

Subcommands​

aibox env create​

aibox env switch​

aibox env list​

aibox env delete​

aibox env status​

Examples​

Shared Files​

Exit Codes​

aibox backup​

Usage​

Options​

What It Does​

Examples​

Exit Codes​

aibox reset​

Usage​

Options​

What It Does​

Examples​

Exit Codes​

aibox update​

Usage​

Options​

What It Does​

Examples​

Exit Codes​

aibox addon​

Subcommands​

aibox addon list​

aibox addon add​

aibox addon remove​

Global Options

aibox init

Usage

Options

What It Does

Examples

Exit Codes

Interactive Mode

aibox sync

Usage

Options

What It Does

Examples

Exit Codes

aibox start

Usage

Options

What It Does

Available Layouts

Examples

Exit Codes

aibox stop

Usage

What It Does

Examples

Exit Codes

aibox remove

Usage

What It Does

Aliases

Examples

Exit Codes

aibox status

Usage

What It Does

Examples

Exit Codes

aibox doctor

Usage

What It Does

Examples

Exit Codes

aibox completions

Usage

Examples

Setup

Exit Codes

aibox env

Subcommands

aibox env create

aibox env switch

aibox env list

aibox env delete

aibox env status

Examples

Shared Files

Exit Codes

aibox backup

Usage

Options

What It Does

Examples

Exit Codes

aibox reset

Usage

Options

What It Does

Examples

Exit Codes

aibox update

Usage

Options

What It Does

Examples

Exit Codes

aibox addon

Subcommands

aibox addon list

aibox addon add

aibox addon remove