CLI Commands

CLI Commands

aibox uses a small verb/resource grammar. aibox.toml is desired state. The established v0 runtime uses apply then up; v1 orchestration uses image, deploy, up (apply-only), and an explicit connect.

Global Options

Core Workflow

aibox init my-app --harness claude --addon python
aibox apply
aibox up --legacy-runtime
aibox down --legacy-runtime
aibox doctor

Command Grammar

aibox init [NAME] [OPTIONS]
aibox apply [RESOURCE] [NAME] [OPTIONS]
aibox up [OPTIONS]
aibox down [--legacy-runtime]
aibox image <build|inspect> [--output human|json]
aibox deploy <plan|apply|status|destroy|logs> [OPTIONS]
aibox connect <NAME> [-- COMMAND...]
aibox get <RESOURCE> [OPTIONS]
aibox describe <RESOURCE> [NAME] [OPTIONS]
aibox set <TARGET> [VALUE] [EXTRA...] [OPTIONS]
aibox edit <RESOURCE>
aibox reset <RESOURCE> [OPTIONS]
aibox delete <RESOURCE> [NAME] [OPTIONS]
aibox create <RESOURCE> [NAME] [OPTIONS]
aibox self <ACTION> [OPTIONS]

init

Create aibox.toml, generated devcontainer files, .aibox-home/, context scaffolding, and provider pointer files.

aibox init
aibox init my-app --harness claude
aibox init runner --profile headless-runner
aibox init my-app --addon python --addon infrastructure
aibox init my-app --harness claude --harness codex
aibox init my-app --context-mode harness-only --harness claude
aibox init my-app --theme catppuccin-mocha

The hidden legacy --context <PKG> option is still accepted as a processkit package selector for compatibility. New configs use [context].mode and, when processkit is enabled, [context].packages.

--context-mode harness-only creates a container-and-harness project with no processkit install, no processkit MCP gateway, no processkit hooks/preauth, no processkit command adapters, and no processkit Migration entities.

apply

Reconcile generated project state with aibox.toml.

aibox apply
aibox apply --no-cache
aibox apply --rebuild
aibox apply --config-only
aibox apply --standardize-config
aibox apply migration MIG-20260430_1200
aibox apply audio
aibox apply env research

Runtime

aibox up                         # v1 deploy apply; does not attach
aibox down                       # v1 guarded deploy destroy
aibox up --legacy-runtime --layout focus
aibox up --legacy-runtime --apply
aibox down --legacy-runtime
aibox get runtime
aibox get runtime --resources
aibox get runtime --resources -o json
aibox describe runtime
aibox delete runtime

aibox up --legacy-runtime starts or creates the v0 workspace container and attaches through tmux. aibox down --legacy-runtime stops that compose project. This compatibility path is deprecated and will be removed on 2026-12-31; migrate to the v1 workflow below. delete runtime removes the v0 container while preserving project files and .aibox-home/.

V1 deployment workflow

V1 has no implicit attach step. up is an alias for a guarded deployment apply; connect only after the deployment operation finishes. The alias requires an enabled [orchestration] configuration.

# Inspect the immutable deployment input, or explicitly build its source contract.
aibox image inspect
aibox image build --output json
aibox image build --push --output json

# Plan without mutation, then reconcile and observe the deployment.
aibox deploy plan --output json
aibox deploy apply --output json
aibox deploy status
aibox deploy logs --service workspace --output json

# Open an interactive shell or run a noninteractive command with its exit code.
aibox connect shell
aibox connect shell -- sh -lc 'make test'

# Alias for deploy apply / guarded deploy destroy; neither attaches a terminal.
aibox up
aibox down

image build is an explicit source-backed operation. Configure it beneath the deployment image with a build context and, when needed, a Dockerfile and named stage:

[orchestration.image]
reference = "ghcr.io/acme/workspace:build"
digest = "sha256:<currently-selected-deployment-manifest-digest>"
platform = "linux-amd64"

[orchestration.image.build]
context = "image-source"
dockerfile = "Containerfile" # optional; relative to context
target = "runtime"            # optional

The command passes this contract as typed Docker or Podman arguments; it does not accept build arguments, environment values, or secrets. A normal build returns its immutable local image ID and deliberately reports no deployable reference. Use --push to publish the explicit tag and verify the runtime’s registry RepoDigests; only then does the output include a pullable reference@sha256:<manifest> value. Copy that digest into orchestration.image.digest when you are ready to promote it for deployment.

Deploy operations always consume the configured immutable image and never build or push implicitly.

Every v1 deploy command accepts -o, --output human|json. JSON is a single machine-readable document on stdout; progress, warnings, and errors use stderr. deploy apply, status, and destroy emit the deployment record in JSON. deploy logs emits { deploymentId, service?, lines }. Human output is concise for terminals. Backend failures preserve their nonzero exit status; connect also forwards the remote command exit code. Kubernetes port-forward stays in the foreground until it is interrupted, while Kubernetes exec uses TTY/stdin only for connections configured as interactive.

down only destroys resources whose deployment record and ownership labels prove that aibox created them. It refuses untracked, foreign, or digest-mismatched resources.

These commands do not enable processkit production delegation. The published processkit protocol remains a separate stable-v1 release gate; until it is available, aibox retains its existing bounded/provisional integration behavior.

get runtime reports the configured container name and detected state (running, stopped, or missing). With --resources, it reports a best-effort resource pressure snapshot from the current Linux runtime by reading cgroupfs and procfs directly rather than shelling out to ps or free.

aibox get runtime --resources includes:

The default table output is compact and human-readable. -o json and -o yaml emit the same field names for automation; unavailable cgroup values are null, while process counts fall back to 0 if /proc cannot be read.

Inspecting Resources

get is compact and scriptable. describe is detailed and human-readable. All list/detail commands support -o, --format table|json|yaml; --output is accepted as a visible alias.

aibox get addon
aibox describe addon python
aibox describe addon-catalog -o json
aibox describe image-provenance-policy -o json
aibox get runtime --resources -o json
aibox describe provider-backends -o json
aibox describe workspace-manifest -o json
aibox get skill
aibox get skill --all --category engineering
aibox describe skill model-recommender-route
aibox get process
aibox describe process release-semver
aibox get migration
aibox get env
aibox describe env
aibox get kit

Preview projections

These describe resources are stable enough for local automation. The workspace manifest has been promoted to aibox.workspace-manifest.v0 because processkit now recognizes Artifact{kind=workspace-manifest}; the other environment-contract projections remain aibox.*.v0-preview until processkit publishes more detailed canonical Artifact schemas.

The preview projections do not create processkit entities and should not be treated as canonical processkit Artifacts yet.

Mutating Resources

set changes config. Use --apply when you want to reconcile immediately.

aibox set theme.mode dark --apply
aibox set theme.name tokyo-night --apply --restart-session
aibox set addon python enabled
aibox set addon python disabled --apply
aibox set skill model-recommender-route enabled
aibox set skill pandas-polars disabled --apply
aibox set migration MIG-20260430_1200 in-progress

Delete explicit resources:

aibox delete addon python
aibox delete addon python --apply
aibox delete skill pandas-polars
aibox delete env research --yes
aibox delete migration MIG-20260430_1200 --reason "Not applicable"

Reset And Backup

Project reset is intentionally scoped; there is no bare destructive reset.

aibox create backup
aibox create backup --dry-run
aibox create backup --output-dir /tmp/my-backup
aibox reset project
aibox reset project --dry-run
aibox reset project --no-backup --yes
aibox reset context --from-processkit v0.25.0 --dry-run

reset project is the practical aibox soft reset. It stops the runtime, backs up aibox-managed project files, preserves auth/cache state from .aibox-home/, removes the managed scaffold, and writes a reset recovery migration briefing when user content is found in the backup. It also removes aibox.toml, so it is not a one-command reinit. Recreate or restore aibox.toml, run aibox init or aibox apply, then review context/migrations/pending/ for the recovery advice.

reset context is plan-only in this release. It reports the processkit-owned context paths that a hard reset would replace from a selected processkit baseline and the project-owned context paths that must be preserved or reviewed. Use normal migrations unless the owner explicitly approves a hard context reset.

Diagnostics

aibox doctor
aibox doctor --integrity
aibox doctor --integrity -o json
aibox doctor audio
aibox doctor security

doctor audio checks host PulseAudio readiness. doctor security runs available dependency/image scanners.

LaTeX container scripts

Named LaTeX documents are configured under [[latex.documents]]. aibox apply deploys the following managed scripts to .aibox-home/.local/bin; they are on PATH inside the development container and are not host CLI commands.

aibox-latex-build                 # build all configured documents
aibox-latex-build overview        # build one configured document
aibox-latex-watch overview        # continuous foreground build inside the container

Host-side aibox up starts the read-only Compose preview sidecar when preview is enabled. It serves every configured PDF and shows a selection page at its root when more than one exists. See LaTeX Build and Preview for container workflow, remote forwarding, and security details.

Self Management

aibox self update --check
aibox self update --dry-run
aibox self update
aibox self completion bash
aibox self uninstall
aibox self uninstall --purge

Removed Old Grammar

The hard-break CLI redesign removed the old top-level command taxonomy.