How do I run `prove (Test2::V0)` with Atlas in CI?

Configure Atlas permissions to `allow` the `prove` tool. Then, in your `atlas run` prompt, instruct Atlas to "run `prove -lr t/`" to execute your `Test2::V0` test suite and surface the TAP output within the JSON event stream for programmatic verification.

Can Atlas manage Perl dependencies with `cpanm` in a headless CI environment?

Yes, Atlas can manage Perl dependencies. Ensure the `bash` tool is allowed in your Atlas permissions. Atlas can then read your `cpanfile` or `Makefile.PL` and execute `cpanm` commands as part of its plan, such as installing missing modules or updating existing ones.

How does Atlas ensure code quality with `perltidy` in CI?

Atlas can run `perltidy` on changed Perl files. By allowing the `perltidy` tool, Atlas can automatically format code edits to match your `.perltidyrc` configuration, ensuring consistent style and reducing merge conflicts before committing changes to your Perl project.

What kind of output does `atlas run --format json` provide for Perl projects?

`atlas run --format json` streams a sequence of JSON objects representing events like agent thoughts, tool calls (e.g., `prove` output), file edits, and session status. This structured data is ideal for programmatic parsing and automation in Perl CI pipelines.

How does Atlas handle permissions for tools like `edit` or `bash` in headless Perl CI?

In headless mode, Atlas relies on pre-configured permissions. You must explicitly set `allow` rules for tools like `edit`, `bash`, `read`, and `todowrite` in your Atlas configuration to prevent interactive `ask` prompts that would halt the CI pipeline, ensuring smooth automation.

Can Atlas understand my Perl module structure and `@EXPORT` lists?

Yes, Atlas indexes Perl code by AST declarations using tree-sitter, allowing it to understand your package structure, `@EXPORT` lists, and module dependencies pulled in by `cpanm`. This enables precise code modifications and refactorings within your Perl codebase.

How can I roll back changes made by Atlas in a Perl CI run?

Atlas snapshots file changes as git patches. If an Atlas-driven change needs to be reverted, you can use standard git commands to diff and roll back the generated patches, providing a robust safety net for your Perl codebase and ensuring full control over automated edits.

Run Atlas Headless in CI for Perl Projects in 2026

To run an Atlas session non-interactively in a Perl CI pipeline and retrieve machine-readable output, invoke `atlas run` with the `--format json` flag, ensuring your `cpanm` dependencies and `prove (Test2::V0)` tests are managed by pre-approved Atlas tools. This enables automated code modifications and verification within your existing Perl development workflow.

How to Run Atlas Headless in Perl CI Pipelines

Running Atlas headless in a Perl CI pipeline in 2026 involves using `atlas run` with specific flags to ensure non-interactive execution and machine-readable output. This approach allows your CI system to automate code modifications, such as adding `use strict` to 10 legacy scripts, without human intervention.

The `atlas run` command is purpose-built for headless execution in CI environments. Its default mode is non-interactive: it accepts a single prompt, streams events to standard output, and gracefully exits once the session becomes idle. For Perl projects, this means Atlas can be instructed to perform tasks like refactoring a `.pm` module or updating a `cpanfile` without requiring any user input. To integrate direct with downstream pipeline steps that need to parse the agent's actions, always include the `--format json` flag. This ensures that instead of human-readable prose, a structured stream of JSON events is emitted, detailing every thought, tool call, and file modification made by Atlas. You can also use `--command` to execute specific slash commands directly, or `--continue` / `--session` to resume a prior session, which is invaluable for multi-stage CI jobs or debugging.

Configuring Atlas for Perl Toolchain Integration

Integrating Atlas with your Perl toolchain requires configuring permissions and ensuring Atlas can interact with `cpanm` and `prove (Test2::V0)`. Atlas can read your `cpanfile` or `Makefile.PL` and understand your module dependencies, making it ready to assist with 20+ package updates.

Atlas is designed to work natively with the Perl ecosystem. It builds its code index by parsing AST declarations using tree-sitter, not blind line windows, allowing it to deeply understand your Perl packages, `@EXPORT` lists, and the modules pulled in by `cpanm`. To enable Atlas to perform actions within your CI pipeline, you must pre-approve the necessary tools through its permission configuration. For a typical Perl workflow, this means allowing `bash` for general shell commands, `read` and `edit` for file operations, `todowrite` for leaving notes, `prove` for running tests, and `perltidy` for formatting. For example, Atlas can be instructed to run `prove -lr t/` to execute your `Test2::V0` test suite, or to invoke `cpanm` to install missing dependencies, all behind a permission prompt that is pre-approved in a headless CI setting. This ensures that Atlas operates within defined boundaries, interacting with your Perl project's specific tools and files like `lib/My/Module.pm` or `t/my_module.t`.

Ensuring Safety and Review in Headless Perl Workflows

Safety and review in headless Perl workflows are managed by Atlas's permission-gated tool calls and unified diffs, preventing unauthorized changes. Every Atlas tool call, like running `prove -lr t/` on 5 test files, is checked against `allow`, `ask`, or `deny` rules before execution, crucial for CI environments.

In a headless CI environment, human oversight is limited, making Atlas's built-in safety mechanisms paramount. Before any tool call, such as `edit` or `bash` (which might execute `cpanm` or `perltidy`), Atlas consults its permission configuration. For headless runs, all necessary tools must be explicitly set to `allow` to prevent interactive `ask` prompts that would halt the pipeline. Atlas also drafts a plan in a read-only plan agent first, asking for approval before switching to a build agent to execute changes. For every file edit, Atlas computes a unified diff and surfaces it. This diff can be captured from the `--format json` output, allowing a later pipeline step to review the proposed changes programmatically. Furthermore, Atlas snapshots file changes as git patches, providing a robust mechanism for diffing and rolling back edits if necessary, ensuring that any automated modifications to your Perl codebase are fully auditable and reversible.

Getting Machine-Readable Output from Headless Atlas Sessions

To obtain machine-readable output from a headless Atlas session in Perl CI, specify the `--format json` flag when invoking `atlas run`. This streams raw event data to stdout, allowing subsequent pipeline steps to parse and act on the agent's actions, such as confirming 3 successful file edits.

When `atlas run` is executed with `--format json`, it streams a continuous sequence of JSON objects to standard output. Each object represents a distinct event in the Atlas session, including agent thoughts, tool calls (e.g., the output from `prove (Test2::V0)` or `perltidy`), file modifications, and session status updates. This structured output is critical for automated CI pipelines, as it allows Perl scripts or other parsing tools to programmatically interpret the agent's progress and outcomes. For instance, a CI job could parse the JSON stream to verify that `prove -lr t/` passed after Atlas made a code change, or to extract the unified diffs for review. This eliminates the need for fragile regex parsing of human-readable logs, providing a reliable and consistent interface for integrating Atlas into complex Perl CI workflows.

Resuming and Forking Atlas Sessions in Perl CI

Resuming or forking a prior Atlas session in a Perl CI pipeline is achieved using `--continue`, `--session`, or `--fork`, enabling complex, multi-step automation. This allows a pipeline to pick up from a previous failure or explore 2 alternative solutions from a common starting point.

Atlas provides powerful capabilities for managing session state, which is particularly useful in CI environments where jobs might be interrupted or require iterative refinement. The `--continue` flag allows an Atlas session to pick up exactly where a previous run left off, using the same session ID. This is invaluable for long-running tasks or when a CI job fails mid-way and needs to be re-run without starting from scratch. Alternatively, `--session <session_id>` can be used to explicitly specify a session to load, while `--fork` creates a new session that branches off from an existing one. This enables parallel exploration of different solutions or allows a pipeline to test multiple approaches to a problem, such as trying different refactoring strategies for a Perl module, all while preserving the context of the original session. These features ensure flexibility and efficiency when integrating Atlas into sophisticated Perl CI/CD pipelines.

Step by step

01Prepare your Perl project: Ensure your project has a `cpanfile` or `Makefile.PL` for dependency management and a `t/` directory for `Test2::V0` tests, along with a `.perltidyrc` for consistent formatting.
02Configure Atlas permissions: Define `allow` rules in your Atlas configuration for tools like `bash`, `read`, `edit`, `todowrite`, `prove`, and `perltidy` to enable headless execution without interactive prompts in your CI environment.
03Invoke Atlas headless with a prompt: Run `atlas run --format json --model github/gpt-4-turbo --prompt "Refactor the `My::Module` package in `lib/My/Module.pm` to use modern Perl idioms and add `use warnings` to all changed files, then run `perltidy` and `prove -lr t/`."
04Parse machine-readable output: Capture the JSON event stream from stdout and process it with a Perl script or `jq` to monitor agent progress, identify file changes, confirm successful `prove (Test2::V0)` runs, and extract unified diffs.
05Review and commit changes (optional): If your pipeline requires manual review, use the generated git patches to inspect changes before staging and committing them, or configure Atlas to stage and commit automatically after successful `perltidy` formatting and `prove` execution.
06Resume a session on failure: If an Atlas session fails, use `atlas run --continue --session <session_id> --format json` in a subsequent CI step to pick up where it left off, allowing for iterative debugging and completion of the task.

Frequently asked questions

How do I run `prove (Test2::V0)` with Atlas in CI?: Configure Atlas permissions to `allow` the `prove` tool. Then, in your `atlas run` prompt, instruct Atlas to "run `prove -lr t/`" to execute your `Test2::V0` test suite and surface the TAP output within the JSON event stream for programmatic verification.
Can Atlas manage Perl dependencies with `cpanm` in a headless CI environment?: Yes, Atlas can manage Perl dependencies. Ensure the `bash` tool is allowed in your Atlas permissions. Atlas can then read your `cpanfile` or `Makefile.PL` and execute `cpanm` commands as part of its plan, such as installing missing modules or updating existing ones.
How does Atlas ensure code quality with `perltidy` in CI?: Atlas can run `perltidy` on changed Perl files. By allowing the `perltidy` tool, Atlas can automatically format code edits to match your `.perltidyrc` configuration, ensuring consistent style and reducing merge conflicts before committing changes to your Perl project.
What kind of output does `atlas run --format json` provide for Perl projects?: `atlas run --format json` streams a sequence of JSON objects representing events like agent thoughts, tool calls (e.g., `prove` output), file edits, and session status. This structured data is ideal for programmatic parsing and automation in Perl CI pipelines.
How does Atlas handle permissions for tools like `edit` or `bash` in headless Perl CI?: In headless mode, Atlas relies on pre-configured permissions. You must explicitly set `allow` rules for tools like `edit`, `bash`, `read`, and `todowrite` in your Atlas configuration to prevent interactive `ask` prompts that would halt the CI pipeline, ensuring smooth automation.
Can Atlas understand my Perl module structure and `@EXPORT` lists?: Yes, Atlas indexes Perl code by AST declarations using tree-sitter, allowing it to understand your package structure, `@EXPORT` lists, and module dependencies pulled in by `cpanm`. This enables precise code modifications and refactorings within your Perl codebase.
How can I roll back changes made by Atlas in a Perl CI run?: Atlas snapshots file changes as git patches. If an Atlas-driven change needs to be reverted, you can use standard git commands to diff and roll back the generated patches, providing a robust safety net for your Perl codebase and ensuring full control over automated edits.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Run Atlas Headless in CI with Atlas (2026 Workflow)

How to run Atlas headless in CI in 2026: atlas run sends one prompt and exits when the session goes idle, with --format json, --command, and --continue for pipeline steps.

Atlas for Perl: A Terminal-Native AI Coding Agent for CPAN Distributions in 2026

Atlas is a terminal-native AI coding agent for Perl in 2026. It reads cpanfile deps and @EXPORT lists, writes Test2::V0 cases, runs prove -lr t/, and runs perltidy on the diff.

Self-review your working diff before committing in Perl with Atlas in 2026

Catch your own mistakes in uncommitted Perl diffs before they reach review or CI. Learn how Atlas helps Perl developers in 2026 self-review code, run `prove`, and `perltidy`.

Rename a symbol across the repo in Perl with Atlas in 2026

Rename Perl functions, classes, or constants across your entire codebase with Atlas in 2026. Leverage lsp, grep, and edit for precise, safe refactoring, ensuring your prove (Test2::V0) tests pass and perltidy formatting

Migrate a Deprecated API Across Every Callsite in Perl with Atlas in 2026

Effortlessly migrate deprecated Perl APIs across your entire codebase using Atlas. Find all callers, track progress, and apply changes safely with prove (Test2::V0) and perltidy.

Run the test suite and triage the failures in Perl with Atlas in 2026

Efficiently triage Perl test failures in 2026 with Atlas. Turn a wall of red `prove (Test2::V0)` output into a prioritized list of distinct root causes, using `grep` and `todowrite`.

Debug a single failing test in Perl with Atlas in 2026

Pinpoint and fix failing Perl tests with Atlas in 2026. Leverage `prove (Test2::V0)` and `cpanm` to isolate issues, walk call graphs, and apply precise code fixes.

Diagnose a Hanging or Long-Running Perl Command with Atlas in 2026

In 2026, Perl developers use Atlas to diagnose why prove (Test2::V0) or cpanm commands hang. Quickly identify if a Perl script is slow or blocked on input.

Browse this resource hub