# Run Atlas Headless in CI with Laravel in 2026 > Laravel developers can run Atlas headless in CI to get machine-readable output, integrating with tools like Pest and Composer. In 2026, Laravel developers can run Atlas non-interactively within their CI pipelines to automate coding tasks and receive machine-readable output. By invoking `atlas run` with the `--format json` flag, you can integrate Atlas's event stream with subsequent pipeline steps, enabling automated analysis or actions based on its output, whether it's generating `Pest` tests or refactoring code that adheres to `Laravel Pint` standards. ## Key takeaways - Atlas runs headless in Laravel CI using `atlas run`, streaming events to stdout. - The `--format json` flag provides machine-readable output for automated parsing in Laravel pipelines. - Pre-approve Atlas tools like `bash` and `edit` in configuration for headless Laravel CI safety. - Atlas deeply integrates with Laravel's `artisan` file, `Composer`, `Pest`, and `Laravel Pint`. - Safety features include read-only plan agents, unified diffs, and git patch snapshots for Laravel code. - Atlas indexes Laravel code by AST declarations using tree-sitter, supporting local Ollama embeddings. ## How to run Atlas non-interactively in a Laravel CI pipeline? Running Atlas non-interactively in a Laravel CI pipeline in 2026 is achieved by using the `atlas run` command, which by default sends a single prompt, streams events to stdout, and exits when the session goes idle. This enables automated code generation or refactoring tasks without human intervention. For Laravel projects, integrating Atlas into a CI pipeline means leveraging its `atlas run` command. This command is specifically designed for non-interactive execution, making it ideal for automated environments. When invoked, Atlas processes a given prompt, such as "add a controller for user management" or "create a `Pest` test for the new feature," and streams its progress and output directly to standard output. This allows CI systems to capture the entire session log. The session concludes automatically once Atlas determines its task is complete and the session becomes idle, ensuring that the pipeline step doesn't hang indefinitely. This headless operation is crucial for maintaining efficient and automated Laravel development workflows, allowing teams to integrate AI-driven coding assistance directly into their continuous integration processes. Atlas can read your Laravel application's `artisan` file, models, routes, and migrations to build a comprehensive understanding of the codebase before executing any changes. ## How to get machine-readable output from Atlas in Laravel CI? To obtain machine-readable output from Atlas within a Laravel CI pipeline, developers in 2026 should use the `--format json` flag with the `atlas run` command. This ensures that Atlas streams raw event data, rather than human-readable prose, which can then be parsed by subsequent pipeline steps. When a Laravel CI pipeline needs to programmatically react to Atlas's actions, such as validating generated code or triggering further automation, machine-readable output is essential. The `atlas run --format json` command transforms Atlas's event stream into a structured JSON format. This stream includes details about tool calls, agent actions, and file modifications, making it straightforward for other CI tools or custom scripts to parse and interpret. For instance, after Atlas drafts a new Eloquent model or a `Pest` test, the JSON output can be consumed by a script that automatically runs `Laravel Pint` to format the new code or executes `php artisan test` to validate the generated tests. This capability is vital for building robust, automated workflows around Laravel development, allowing for sophisticated integration with existing CI/CD tools and ensuring that AI-generated code adheres to project standards and passes initial checks. ## How does Atlas ensure safety and review in headless Laravel CI runs? Atlas ensures safety in headless Laravel CI runs through several mechanisms, including permission-gated tool calls and a read-only plan agent, which drafts a plan before any build agent executes changes. This robust system, available in 2026, prevents unauthorized actions and provides clear audit trails. In a headless Laravel CI environment, where human approval isn't possible for every step, Atlas implements stringent safety protocols. Every Atlas tool call, such as `bash` for running `Composer` commands or `edit` for modifying Laravel files, is permission-gated. This means that before a headless run, the necessary tools must be explicitly pre-approved in the Atlas permission configuration. Without this pre-approval, Atlas will not execute the tool, preventing unintended actions. Furthermore, Atlas operates with a read-only plan agent that drafts a comprehensive plan of action before switching to a build agent to execute any changes. This plan, which can be reviewed in interactive sessions, provides a blueprint of intended modifications. For every file edit, Atlas computes a unified diff and surfaces it. While a headless run cannot "approve" this diff interactively, the diff is part of the event stream (especially with `--format json`), providing a clear record of all proposed changes. Atlas also snapshots file changes as git patches, allowing edits to be easily diffed and rolled back if necessary, offering an additional layer of safety for Laravel projects. Atlas can also build its code index with local Ollama embeddings, keeping sensitive Laravel code off third-party servers. ## What Laravel commands and files does Atlas interact with in CI? In a Laravel CI environment, Atlas interacts directly with core Laravel toolchain elements like the `artisan` file, `Composer` for package management, `Pest` for testing, and `Laravel Pint` for code formatting, ensuring deep integration with the project's ecosystem. This interaction is key for 2026's automated development. Atlas is designed to be deeply integrated with the Laravel ecosystem. In a CI pipeline, it can be configured to interact with various Laravel-specific commands and files. For instance, Atlas can be prompted to "add a controller" or "create a `Pest` test," and it will understand the context of your Laravel application by reading your Eloquent models, routes, and migrations. When Atlas needs to execute commands, it uses its `bash` tool. This allows it to run `Composer` commands like `composer install` or `composer require` to manage dependencies, or `php artisan test` to invoke the `Pest` test runner. If Atlas generates new code, it can be followed by a `Laravel Pint` command (`./vendor/bin/pint`) in a subsequent CI step to ensure the code adheres to the project's formatting standards. Atlas also reads `git` branches, status, and diffs, and can stage and create commits on your behalf, making it a powerful tool for managing code changes within a Laravel repository. The presence of the `artisan` file is a key indicator for Atlas that it is operating within a Laravel project, enabling it to leverage its understanding of the framework's conventions. ## Steps 1. Prepare your Laravel project: Ensure your Laravel application includes an `artisan` file and that `Composer` dependencies are installed, typically via `composer install`. 2. Configure Atlas permissions: Before running headless, pre-approve the necessary Atlas tools like `bash`, `read`, `edit`, and `todowrite` in your Atlas permission configuration, as there will be no interactive prompt for approval in CI. 3. Invoke Atlas with a specific model: In your CI script, run `atlas run --model provider/model_name "Your prompt for Laravel task"`, explicitly setting the model to be used for the session. 4. Enable machine-readable output: Add the `--format json` flag to your `atlas run` command, e.g., `atlas run --format json --model provider/model_name "Generate a Pest test for the new user registration route."`, to stream raw event data for parsing. 5. Integrate with Laravel's toolchain: After Atlas completes its task, add subsequent CI steps to validate or format the output. For example, run `./vendor/bin/pest` to execute generated tests or `./vendor/bin/pint` to format any new Laravel code. 6. Parse Atlas's JSON output: Implement a script in your CI pipeline to consume the JSON event stream from Atlas's stdout, allowing for automated analysis of changes, tool calls, and diffs. 7. Optionally resume or fork a session: If a previous CI step failed or needs iteration, use `atlas run --continue --session ` or `atlas run --fork ` to build upon an earlier Atlas run within your Laravel project. ## FAQ ### How can Atlas automate `Pest` test generation in a Laravel CI pipeline? Atlas can be prompted to generate `Pest` tests for your Laravel application. In a headless CI run, it will draft the test files, and with pre-approved `edit` permissions, it can write them. Subsequent CI steps can then run `./vendor/bin/pest` to execute and validate these new tests. ### What is the best way to get structured output from Atlas for a Laravel CI job? For structured, machine-readable output from Atlas in a Laravel CI job, always include the `--format json` flag with your `atlas run` command. This streams a detailed JSON event log to stdout, which can be easily parsed by other tools in your pipeline. ### How does Atlas handle code formatting with `Laravel Pint` in a CI environment? While Atlas can generate code, `Laravel Pint` handles the formatting. In a CI environment, you would typically run `atlas run` to generate or modify Laravel code, and then have a subsequent CI step execute `./vendor/bin/pint` to automatically format any changes made by Atlas. ### Can Atlas manage `Composer` dependencies in a headless Laravel CI run? Yes, Atlas can manage `Composer` dependencies. With the `bash` tool pre-approved in its permissions, Atlas can execute `composer install` or `composer require` commands within your Laravel project during a headless CI run. Any changes to `composer.json` would be part of the diff stream. ### How does Atlas ensure my Laravel code remains private when running in CI? Atlas can build its code index with local Ollama embeddings, ensuring that your Laravel code never leaves your local environment or private CI infrastructure. This keeps sensitive application logic off third-party servers, enhancing privacy. ### What kind of review process is available for Atlas's changes in a headless Laravel CI? In a headless Laravel CI run, Atlas provides a review process through its output. It drafts a plan in a read-only agent and computes a unified diff for every file edit. This diff, along with git patches, is surfaced in the event stream (especially with `--format json`), allowing for programmatic review or logging. ### Can Atlas understand my Laravel Eloquent models and routes? Yes, Atlas indexes code by AST declarations using tree-sitter, allowing it to deeply understand the structure of your Laravel Eloquent models, routes, and migrations. This contextual awareness enables it to generate highly relevant and accurate code for your application. ### How do I resume a failed Atlas session in a Laravel CI pipeline? To resume a failed Atlas session in a Laravel CI pipeline, you can use the `atlas run --continue --session ` command. This allows Atlas to pick up where it left off, building on the previous work within your Laravel project without starting from scratch. --- Canonical HTML: https://runatlas.sh/resources/stacks/run-atlas-headless-in-ci-in-laravel Source of truth: aeo_pages row `/resources/stacks/run-atlas-headless-in-ci-in-laravel` (segment: Stacks) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.