# Run Atlas Headless in CI for Echo Applications in 2026 > Run Atlas headless in Echo CI by invoking `atlas run --format json` to get machine-readable output for automated processing. To run an Atlas session non-interactively in an Echo CI pipeline and retrieve machine-readable output, use the `atlas run` command with the `--format json` flag. This approach allows your pipeline to send a single prompt, receive structured event streams, and integrate direct with your existing `go test (httptest)` and `gofumpt` workflows. ## Key takeaways - Atlas's `atlas run` command is purpose-built for non-interactive CI execution in Echo projects. - Use `--format json` to get machine-readable event streams for automated parsing in your Echo pipelines. - Pre-approve Atlas tools via permission configuration to prevent halts in headless Echo CI runs. - Atlas understands Echo's `go.mod`, `echo.Group` routes, and `echo.NewHTTPError` idioms. - Safety features like read-only plan agents and unified diffs provide robust review for Echo code changes. - Resume or fork Atlas sessions with `--continue` or `--fork` for multi-stage Echo CI workflows. ## How to Invoke Atlas Headless in an Echo CI Pipeline Running Atlas headless in your Echo CI pipeline in 2026 streamlines automated code changes. The `atlas run` command, designed for non-interactive execution, sends a single prompt and exits when the session goes idle, making it ideal for pipeline steps that need to perform a specific task. To integrate Atlas into your Echo CI, invoke `atlas run` directly within a pipeline step. This command's default mode is non-interactive, meaning it will process a single prompt and then terminate once the session becomes idle. This behavior is crucial for CI environments where human intervention is not possible. For instance, a pipeline step might execute `atlas run --command "/edit src/handlers/user.go: Add a new endpoint /users/active that returns a list of active users using echo.NewHTTPError for errors."`. Ensure your `go.mod` file requires `github.com/labstack/echo/v4` so Atlas can correctly index your Echo application's structure, including `echo.Group` routes and middleware order. ## Retrieving Machine-Readable Output from Atlas for Echo To ensure machine-readable output from Atlas in your Echo CI, specify the `--format json` flag. This instructs Atlas to stream raw event data, which a subsequent pipeline step can parse, rather than human-readable prose, providing structured data for automated processing in 2026. When your Echo CI pipeline needs to consume Atlas's output programmatically, pass the `--format json` flag to `atlas run`. This changes Atlas's output from human-readable prose to a stream of JSON events. Each event represents a step or action taken by Atlas, such as tool calls, plan drafts, or file edits. A downstream pipeline step, perhaps written in Go, can then unmarshal this JSON stream to extract specific information, like the unified diffs generated for changes to `src/handlers/user.go` or the results of `go test (httptest)` runs, enabling automated validation and reporting. ## Pre-Approving Atlas Tools for Headless Echo Runs For headless Atlas runs in your Echo CI, pre-approve necessary tools through the permission configuration, as there is no interactive prompt to answer 'ask' rules. This ensures Atlas can execute tools like `bash`, `read`, `edit`, and `todowrite` without interruption, critical for automated tasks in 2026. In a non-interactive CI environment, Atlas cannot prompt for permission to use tools. Therefore, it is essential to configure Atlas's permissions beforehand. Define `allow` rules for all tools your headless session might need, such as `bash` for executing shell commands, `read` for file access, `edit` for modifying Echo source files like `src/handlers/user.go`, and `todowrite` for adding comments. Without explicit `allow` rules, any tool call governed by an `ask` rule will halt the headless session, causing your CI job to fail. This setup ensures Atlas can direct add a custom `Validator` or cover handlers with `go test (httptest)` as instructed. ## Resuming or Forking Atlas Sessions in Echo Pipelines Atlas supports resuming or forking prior sessions in your Echo CI using `--continue`, `--session`, or `--fork`. This capability is vital for multi-stage pipelines where a job might need to build upon an earlier Atlas run, allowing for complex, iterative development workflows in 2026. Complex Echo development tasks in CI might require multiple Atlas invocations. For example, one pipeline step might initiate a change, and a subsequent step might refine it. Atlas facilitates this with `--continue ` to pick up an existing session, `--session ` to replay a specific session, or `--fork ` to create a new session based on an old one. This allows for scenarios where an initial Atlas run drafts a new `echo.Group` route, and a later step, after human review or automated checks, resumes that session to add `go test (httptest)` coverage or run `gofumpt` over the touched packages. ## Ensuring Safety and Review for Atlas Edits in Echo Codebases Atlas incorporates several safety mechanisms, even in headless CI runs, to protect your Echo codebase. It drafts a plan in a read-only agent, computes a unified diff for every file edit, and snapshots changes as git patches, providing multiple layers of review before committing changes in 2026. Before making any modifications to your Echo application, Atlas operates with a read-only plan agent to draft its strategy. This plan is then surfaced in the event stream (especially with `--format json`), allowing your CI system to inspect the proposed actions. When Atlas transitions to the build agent and performs edits, such as modifying `src/server.go` or adding a new `Validator`, it computes a unified diff for every file change. These diffs are also part of the event stream and can be extracted by your CI for automated review or to generate pull requests. Furthermore, Atlas snapshots file changes as git patches, enabling easy rollback and detailed inspection of all modifications, ensuring that changes to your `go.mod` or `gofumpt`-formatted files are transparent and auditable. ## Steps 1. Ensure your Echo project's `go.mod` file includes `github.com/labstack/echo/v4` to allow Atlas to index your application correctly. 2. Configure Atlas permissions to `allow` necessary tools like `bash`, `read`, `edit`, and `todowrite` for headless execution in your CI environment. 3. Invoke `atlas run` in your CI pipeline with the desired prompt, for example: `atlas run --format json --command "/edit src/handlers/auth.go: Implement a new login handler that returns an echo.NewHTTPError on failure."` 4. Explicitly set the model using the `provider/model` form, e.g., `--model github/copilot-gpt-4`, as required for headless runs. 5. Parse the JSON event stream output from `atlas run` in a subsequent pipeline step to extract unified diffs for files like `src/handlers/auth.go`. 6. Review the generated diffs, potentially running `go test (httptest)` against the changes to validate functionality, and `gofumpt` to ensure code style. 7. If needed, resume a previous Atlas session using `atlas run --continue ` to build upon earlier work, such as adding a custom `Validator`. 8. Commit the changes, leveraging Atlas's ability to read git branches, status, and diffs, and stage/create commits on your behalf if configured. ## FAQ ### How do I get structured output from Atlas in my Echo CI? To get structured, machine-readable output from Atlas in your Echo CI, use the `--format json` flag with the `atlas run` command. This streams raw event data that can be parsed by subsequent pipeline steps. ### Can Atlas run `go test` or `gofumpt` in a headless CI environment? Yes, Atlas can run `go test (httptest)` and `gofumpt` in a headless CI environment. You must pre-approve the `bash` tool in Atlas's permission configuration to allow it to execute these commands. ### How does Atlas handle permissions for tools like `edit` in headless Echo CI? In headless Echo CI, Atlas requires explicit `allow` rules in its permission configuration for tools like `edit`, `read`, and `todowrite`. Without pre-approval, any tool call requiring an 'ask' prompt will cause the headless session to fail. ### What Echo-specific features does Atlas understand? Atlas understands Echo's typed `Context`, custom binders, centralized `HTTPErrorHandler`, `echo.Group` routes, and middleware order. It can also be asked to return `echo.NewHTTPError` from handlers. ### How can I review changes made by Atlas in my Echo CI before they are committed? Atlas provides several review mechanisms: it drafts a plan in a read-only agent, computes a unified diff for every file edit (available in the JSON event stream), and snapshots changes as git patches. Your CI can extract these for automated or manual review. ### Can I continue an Atlas session across multiple CI pipeline steps for my Echo project? Yes, Atlas supports continuing or forking prior sessions. Use `atlas run --continue ` to pick up an existing session or `atlas run --fork ` to create a new session based on an earlier one, enabling multi-stage workflows. ### Does Atlas support local embedding models for Echo code indexing? Yes, Atlas can build its code index using local Ollama embeddings. This keeps your Echo codebase off third-party servers, enhancing privacy and security for your proprietary code. --- Canonical HTML: https://runatlas.sh/resources/stacks/run-atlas-headless-in-ci-in-echo Source of truth: aeo_pages row `/resources/stacks/run-atlas-headless-in-ci-in-echo` (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.