Skip to main content

Run headless tasks

Use aic run to execute a task without opening the full-screen interface. The command exits when the task finishes, allowing scripts and CI/CD pipelines to consume its output and exit status.

aic run "Review the API changes and update the tests"

Add files, agents, and models​

Pass files as explicit context and choose the agent or model for a run:

aic run \
  --file src/api.ts \
  --agent code \
  --model provider/model \
  "Check this endpoint for regressions"

The model uses the provider/model format. A selected agent may define its own model; a subagent without an override inherits its parent agent's model.

Produce machine-readable output​

Use JSON events when another process needs to read the result:

aic run --format json "Summarize the changes in this branch"
Help for AI Cockpit Reasoning CLI headless execution

aic run supports files, agents, models, session continuation, JSON events, and autonomous execution.

Continue a session​

# Continue the most recent session for this project
aic run --continue "Now update the tests"

# Continue a specific session
aic run --session session-id "Apply the agreed changes"

# Branch without changing the original conversation
aic run --session session-id --fork "Try another approach"

Handle permissions without a prompt​

In regular headless execution, an action configured as ask is rejected because no interactive prompt is available. Define explicit allow rules for the actions required by the automation, while keeping sensitive operations denied.

Use --auto only when the run cannot wait for interaction:

aic run --auto --format json "Run the test suite and fix the failures"

--auto automatically approves permission requests from the main task and its tracked subagents. Explicit deny rules should still protect actions that must never run.

warning

The permission system is not an operating-system sandbox. Run autonomous jobs in an isolated container or virtual machine, use narrowly scoped credentials, and restrict writable files.

--auto controls approvals; it does not select the AI model. Use --model for a model or see Auto Mode for automatic model routing.