To run an Atlas session non-interactively in a pipeline and get machine-readable output back, use `atlas run`. Its default mode is non-interactive: it sends a single prompt, streams events to stdout, and exits when the session goes idle. Pass --format json when a later pipeline step needs to parse the event stream rather than read prose. Set the model explicitly, because the GitHub path requires provider/model form and rejects anything else. Pre-approve the tools the job needs through the permission config, because a headless run has nobody to answer an ask prompt. Use --command for slash-command execution, and --continue, --session, or --fork to resume or replay a prior run.
How do I run Atlas non-interactively in a CI pipeline?
Invoke `atlas run` with the prompt as an argument. `atlas run` is built for CI: its default mode is non-interactive, so it sends a single prompt, streams events to stdout, and exits when the session goes idle, which is exactly the contract a 2026 pipeline step needs.
A pipeline step needs three things from a command: it takes input up front, it produces output on stdout, and it terminates on its own. The interactive TUI satisfies none of them. `atlas run` satisfies all three by design. The prompt is an argument rather than something typed at a cursor, the event stream goes to stdout where the runner captures it, and the exit is tied to the session going idle rather than to a human closing the terminal.
How do I get machine-readable output from Atlas in CI?
Pass --format json to `atlas run` when a later pipeline step needs to parse the event stream rather than read prose. Without --format json, the output of an Atlas headless run is text meant for a human reader, which no downstream job in 2026 should be trying to regex.
The distinction is between output a person reads in a build log and output a program consumes. --format json gives raw event streaming, so the next step in the pipeline can parse events instead of scraping prose. That is what makes it possible to gate a deploy on what Atlas found, post a structured comment, or fan the result into another job. Parsing human-readable prose works until the phrasing changes, and the phrasing always changes.
What model format does Atlas require in a headless run?
Set the model explicitly in every headless Atlas run in 2026. The GitHub path requires provider/model form and rejects anything else, so a bare model name fails up front rather than falling back to a default the pipeline never intended to use, and never chose on purpose.
Failing up front is the desirable behavior for a CI job. A silent fallback to a default model would produce a run that succeeds, costs money, and used a model nobody chose, which is a bug that surfaces weeks later on a bill. Requiring provider/model form makes the pipeline's intent explicit in the workflow file, where it is reviewable. Atlas also lets you switch the active model and provider on the fly with favorites and recents when you are working interactively, but a pipeline should pin exactly one.
How do permissions work when Atlas runs headless with nobody to approve?
Pre-approve the tools the job needs through the permission config, because a headless Atlas run has nobody to answer an ask prompt. Every Atlas tool call is permission-gated against 3 rule types, allow, ask, and deny, before it runs, and in CI an ask has no human on the other end.
The design consequence is that a headless job's permission config is its security boundary, and it should be written as one. Put on allow only the tools the job genuinely needs, such as bash for the test command, read for the files it inspects, edit if the job is expected to change code, and todowrite for its findings. Leave everything else denied. A job that is allowed to do only what it was hired to do cannot be talked into doing something else by a prompt injected into an issue body.
How do I resume or replay an Atlas CI run?
Resume or fork a prior Atlas session with --continue, --session, or --fork when a job needs to build on an earlier run. Session resumption is what turns 3 separate pipeline steps into one continuous piece of work rather than three agents starting from nothing.
A multi-step pipeline often wants the second step to know what the first step found. Re-prompting from scratch throws that away and pays for the context twice. --continue picks up the previous session, --session targets a specific one by id, and --fork branches from an existing session so an experimental step does not contaminate the original. Because a pipeline step can be replayed or resumed, a failed job can be re-run from where it stopped instead of from the top.
Can Atlas run a slash command in CI instead of a prompt?
Yes. `atlas run` supports --command for slash-command execution, so a CI job can invoke a named command rather than repeating a long prompt string in every workflow file. Keeping the prompt in one command definition beats copy-pasting the same 40 lines into 5 jobs.
Slash-command execution in a pipeline has the same benefit it has interactively: the instruction lives in one place, gets reviewed like code, and changes for every caller at once. A workflow file that inlines its prompt drifts, because someone updates one job's copy and not the other four. Inside the headless run, the tools available to the command are still the ones the permission config allows, and bash, read, edit, and todowrite are the ones a CI job typically needs.
Step by step
- 01Invoke `atlas run` with the prompt as an argument. The default mode sends one prompt and exits when the session goes idle.
- 02Set the model explicitly in provider/model form, because the GitHub path requires provider/model form and rejects anything else.
- 03Pre-approve the tools the job needs through the permission config, since a headless run has nobody to answer an ask prompt. bash, read, edit, and todowrite are the usual set.
- 04Pass --format json when a later pipeline step needs to parse the event stream rather than read prose.
- 05Use --command for slash-command execution so the prompt lives in one reviewed definition instead of being copied into every workflow file.
- 06Resume or fork a prior session with --continue, --session, or --fork when a job needs to build on an earlier run.
- 07Capture the streamed events from stdout in the CI runner and gate the next step on what the parsed output contains.
Frequently asked questions
- how do I run an AI coding agent in CI without a terminal
- Use `atlas run` with the prompt as an argument. Its default mode is non-interactive: it sends a single prompt, streams events to stdout, and exits when the session goes idle, which is the contract a CI step needs.
- how do I get JSON output from atlas run?
- Pass --format json. `atlas run` supports --format json for raw event streaming, so a later pipeline step can parse the event stream rather than read prose. Scraping human-readable output works until someone rewords it.
- why does Atlas reject my model name in a GitHub workflow?
- The GitHub path requires provider/model form and rejects anything else. A bare model name fails up front rather than silently falling back to a default the pipeline never chose, which would be a bug you find on a bill weeks later.
- how do permissions work when Atlas runs with no human present?
- Pre-approve the tools the job needs through the permission config, because a headless run has nobody to answer an ask prompt. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so an unapproved tool simply does not run.
- can I resume a previous Atlas session from a CI job?
- Yes. Use --continue to pick up the previous session, --session to target a specific one, or --fork to branch from an existing session. Because a pipeline step can be replayed or resumed, a failed job restarts from where it stopped.
- can atlas run execute a slash command instead of a prompt?
- Yes. `atlas run` supports --command for slash-command execution, so the instruction lives in one reviewed command definition instead of being copy-pasted into every workflow file, where the copies inevitably drift apart.
- which tools does a headless Atlas CI job usually need?
- bash for running the build and tests, read for inspecting files, edit if the job is expected to change code, and todowrite for reporting findings. Allow only those in the permission config and leave the rest denied.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Run Atlas Headless in CI for Clojure Projects in 2026
Automate Atlas in your Clojure CI/CD pipeline. Learn to run Atlas headless with `deps.edn`, `kaocha`, and `cljfmt` for machine-readable output and safe code changes in 2026.
Run Atlas Headless in CI for Three.js Projects in 2026
Automate Three.js code improvements in CI with Atlas. Run Atlas headless to fix memory leaks and optimize render loops, getting machine-readable output for vitest and prettier.
Run Atlas Headless in CI for WebAssembly Projects in 2026
In 2026, run Atlas headless in your WebAssembly CI pipelines to automate code changes and get machine-readable output. Leverage `wasm-pack test` and `cargo wasm-bindgen` for direct integration.
Run Atlas Headless in CI with TensorFlow in 2026
Automate TensorFlow model optimization and testing in CI pipelines using Atlas. Learn to run Atlas headless with `uv`, `pytest`, and `black` for machine-readable output in 2026.
Run Atlas Headless in CI for Expo Projects in 2026
Automate Atlas in your Expo CI/CD pipelines by 2026. Get machine-readable output for `jest-expo` and `prettier` tasks, ensuring reproducible builds with `npx expo install`.
Run Atlas Headless in CI for Django Projects in 2026
In 2026, Django developers can run Atlas headless in CI pipelines to automate code changes and get machine-readable output. Integrate Atlas with pytest-django and uv for efficient, automated development workflows.
Run Atlas Headless in CI for Unreal Engine in 2026
Automate Atlas sessions in your Unreal Engine CI/CD pipelines. Get machine-readable output, manage dependencies with Build.cs, and format code with clang-format.
Run Atlas Headless in CI for Pandas Workflows in 2026
Automate Pandas code improvements in CI with Atlas. Get machine-readable output, integrate with pytest (assert_frame_equal), uv, and ruff format for robust, non-interactive workflows.