To run an Atlas session non-interactively in a COBOL 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, process the streamed events, and integrate direct with tools like `GnuCOBOL cobc` and `COBOL Check` for automated COBOL development.
How do I run Atlas headless in CI for COBOL development?
Running Atlas headless in your COBOL CI pipeline in 2026 is achieved by invoking `atlas run` with your desired prompt. This command operates non-interactively by default, sending a single prompt and exiting once the session becomes idle, making it ideal for automated COBOL tasks.
Atlas is designed for non-interactive execution in CI environments, particularly useful for COBOL projects where batch logic and `PICTURE` clauses are central. When you execute `atlas run` within your pipeline, Atlas processes the provided prompt, interacts with your `.cbl` programs and `COPY` members, and then concludes its session. This allows for automated tasks such as refactoring `IDENTIFICATION`, `DATA`, or `PROCEDURE` divisions, or updating `COPY` members without requiring manual intervention. The default behavior of `atlas run` is to stream events to standard output, which can then be captured and processed by subsequent steps in your CI workflow, ensuring that your COBOL codebase remains consistent and up-to-date.
How do I configure Atlas permissions for COBOL CI pipelines?
For headless Atlas runs in COBOL CI, pre-approving necessary tools through the permission configuration is crucial, as there is no interactive user to answer 'ask' prompts. This ensures that Atlas can execute `bash`, `read`, `edit`, and `todowrite` commands without interruption in 2026.
Atlas employs a robust permission system where every tool call is gated against `allow`, `ask`, and `deny` rules. In a headless CI environment, interactive 'ask' prompts are not feasible. Therefore, for your COBOL pipelines, you must pre-configure permissions to `allow` the tools Atlas will need to operate on your codebase. This includes general tools like `bash` for executing shell commands, `read` for accessing file content, `edit` for modifying COBOL source files, and `todowrite` for creating new files or updating existing ones. Specifically, if Atlas needs to compile COBOL code with `GnuCOBOL cobc` or run tests with `COBOL Check`, these actions must be explicitly permitted in the Atlas configuration, allowing the agent to proceed with its plan without requiring human approval during the automated run.
How does Atlas provide machine-readable output for COBOL CI?
Atlas provides machine-readable output for COBOL CI pipelines by using the `--format json` flag with `atlas run`. This streams raw event data to stdout, allowing a later pipeline step to parse the structured JSON output rather than relying on human-readable prose in 2026.
When integrating Atlas into a COBOL CI pipeline, obtaining structured, machine-readable output is essential for automated processing and decision-making. By appending `--format json` to your `atlas run` command, Atlas will stream its session events as a continuous JSON array to standard output. This raw event stream contains detailed information about the agent's actions, tool calls, and generated diffs, all in a parseable format. A subsequent step in your CI pipeline can then consume this JSON output, extract relevant data points,such as the success or failure of a COBOL compilation with `GnuCOBOL cobc`, the results of `COBOL Check` tests, or the specifics of proposed code changes,and use this information to trigger further actions, generate reports, or update status dashboards. This eliminates the need for complex regex parsing of human-readable logs, streamlining your automated COBOL workflows.
How does Atlas ensure safe COBOL code changes in CI?
Atlas ensures safe COBOL code changes in CI by computing a unified diff for every file edit and surfacing it for approval, even in headless mode. This allows for review against `fixed-format column rules` and `Z Open Editor formatter` standards before changes are committed in 2026.
Safety and review are paramount when automating code changes, especially in COBOL environments with their strict `fixed-format column rules` and `PICTURE` clause considerations. Atlas addresses this by generating a unified diff for every proposed file edit. While a headless run cannot prompt for interactive approval, the diffs are still part of the event stream when using `--format json`. This allows your CI pipeline to capture and analyze these diffs. You can configure a pipeline step to automatically check these diffs against COBOL coding standards, verify compliance with `Z Open Editor formatter` output, or even trigger a human review process for critical changes before they are merged. Furthermore, Atlas snapshots file changes as git patches, providing a robust mechanism to diff edits and roll back any unintended modifications, ensuring that your COBOL codebase remains stable and correct.
How do I manage Atlas sessions for COBOL CI job resumption?
Managing Atlas sessions for COBOL CI job resumption is possible using the `--continue`, `--session`, or `--fork` flags with `atlas run`. This allows a pipeline step to replay or resume a prior Atlas session, building upon previous work on your COBOL codebase in 2026.
In complex COBOL CI pipelines, it's often necessary to resume or build upon previous work without starting from scratch. Atlas supports this through its session management capabilities. The `--continue` flag allows you to pick up an existing session from where it left off, which is useful if a pipeline job was interrupted or needs to perform additional steps. The `--session` flag lets you explicitly specify a session ID to interact with, enabling precise control over which prior run Atlas should reference. Alternatively, `--fork` creates a new session based on an existing one, allowing you to explore alternative solutions or apply different prompts while preserving the original session's context. These features are invaluable for iterative COBOL development in CI, enabling efficient debugging, refinement of agent prompts, and multi-stage pipeline execution where each stage builds on the COBOL code changes from the previous one.
Step by step
- 01Initialize Atlas in your COBOL project directory where `.cbl` programs and `COPY` members reside, ensuring Atlas can read `IDENTIFICATION`, `DATA`, and `PROCEDURE` divisions.
- 02Configure Atlas permissions to `allow` necessary tools like `bash`, `read`, `edit`, and `todowrite`, and specifically permit `GnuCOBOL cobc` for compilation and `COBOL Check` for test execution.
- 03Invoke `atlas run` in your CI pipeline with a COBOL-specific prompt, for example, `atlas run "Refactor the 'CALCULATE-TOTAL' paragraph in MYPROG.cbl to improve performance." --format json`.
- 04Ensure the `--format json` flag is passed to `atlas run` so that the event stream is machine-readable for subsequent pipeline steps.
- 05Capture the JSON output from `stdout` and parse it in a later pipeline step to analyze proposed changes, `GnuCOBOL cobc` compilation results, or `COBOL Check` test outcomes.
- 06Review the unified diffs generated by Atlas against COBOL `fixed-format column rules` and `Z Open Editor formatter` standards, either programmatically or through a human review gate.
- 07Optionally, use `atlas run --continue <session_id>` or `atlas run --fork <session_id>` to resume or build upon a prior Atlas session if the CI job requires iterative refinement of COBOL code.
Frequently asked questions
- Can Atlas understand COBOL copybooks and PICTURE clauses?
- Yes, Atlas indexes COBOL code by AST declarations using tree-sitter, allowing it to understand `IDENTIFICATION`, `DATA`, and `PROCEDURE` divisions, including `COPY` members and `PICTURE` clauses. This deep understanding ensures relevant context for COBOL-specific tasks.
- How does Atlas integrate with GnuCOBOL cobc in CI?
- Atlas integrates with `GnuCOBOL cobc` by allowing you to define tool permissions that permit Atlas to execute `cobc` commands. In a headless CI run, Atlas can then compile your COBOL programs as part of its plan, with compilation results streamed as part of the JSON output.
- What output format does Atlas provide for CI pipelines?
- For CI pipelines, Atlas provides a machine-readable JSON output format when `atlas run` is invoked with the `--format json` flag. This streams raw event data to stdout, which can be easily parsed by subsequent pipeline steps for automated processing.
- How does Atlas handle permissions for COBOL tools in headless mode?
- In headless mode, Atlas requires pre-approved permissions for all tools it will use, such as `bash`, `read`, `edit`, `todowrite`, `GnuCOBOL cobc`, and `COBOL Check`. This is because there is no interactive user to respond to 'ask' prompts, ensuring uninterrupted execution in CI.
- Can I resume an Atlas session in a COBOL CI pipeline if it fails?
- Yes, you can resume an Atlas session in a COBOL CI pipeline using the `atlas run --continue <session_id>` command. This allows the pipeline to pick up from where a previous session left off, saving time and resources by not restarting the entire process.
- How does Atlas ensure code quality for COBOL changes?
- Atlas ensures COBOL code quality by generating a unified diff for every file edit, which can be reviewed against `fixed-format column rules` and `Z Open Editor formatter` standards. It also drafts a plan in a read-only agent before making changes, and snapshots edits as git patches for rollback.
- Does Atlas support local Ollama embeddings for COBOL code indexing?
- Yes, Atlas can build its code index with local Ollama embeddings. This capability is crucial for COBOL projects, as it allows code to remain off third-party servers, addressing potential data privacy and security concerns for sensitive enterprise COBOL applications.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated 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 COBOL: Copybooks, PIC Clauses, and GnuCOBOL in 2026
Atlas is a terminal-native AI coding agent for COBOL in 2026. It reads your divisions and copybooks, explains a paragraph before touching it, and compiles with cobc under GnuCOBOL.
Diagnose a Hanging or Long-Running Command in COBOL with Atlas in 2026
Diagnose hanging COBOL commands in 2026 with Atlas. Identify if GnuCOBOL cobc builds or COBOL Check tests are slow or blocked on input, and unblock them using Atlas's AI agent.
Plan a multi-file change before editing in COBOL with Atlas in 2026
Design and review multi-file COBOL changes before modifying a single line with Atlas. Leverage GnuCOBOL cobc and COBOL Check for safe, pre-approved modifications in 2026.
Run the COBOL Test Suite and Triage Failures with Atlas in 2026
In 2026, COBOL developers use Atlas to run COBOL Check test suites, triage failures into distinct root causes, and fix issues efficiently, all within the terminal.
Document a COBOL Module with a README in 2026 using Atlas
In 2026, COBOL developers use Atlas to generate accurate READMEs directly from live code. Atlas integrates with GnuCOBOL cobc and COBOL Check, ensuring documentation reflects current behavior.
Migrate a Deprecated API Across Every Callsite in COBOL with Atlas in 2026
Migrate deprecated COBOL APIs across your entire codebase with Atlas. Ensure every callsite is updated, leveraging `GnuCOBOL cobc` and `COBOL Check` for a complete, verified transition in 2026.
Debug a single failing test in COBOL with Atlas in 2026
Pinpoint and fix failing COBOL tests efficiently with Atlas in 2026. Leverage GnuCOBOL cobc, COBOL Check, and Z Open Editor formatter for precise debugging.