How do I run Atlas in a Nim CI pipeline without user interaction?

You run `atlas run` with your prompt and the `--format json` flag. This executes Atlas non-interactively, streaming machine-readable events to stdout, and exits when the session goes idle.

What Nim-specific tools does Atlas integrate with in CI?

Atlas integrates with the `nimble` package manager, the `nimble test` runner for unit tests, and the `nph` formatter, allowing it to understand, modify, and validate Nim code.

How does Atlas handle permissions for file edits in a headless Nim CI environment?

For headless runs, all Atlas tools like `edit` and `bash` must be pre-approved in the permission configuration. This bypasses interactive `ask` prompts, ensuring uninterrupted execution in your Nim CI.

Can Atlas help me add unit tests to my Nim project in CI?

Yes, you can prompt Atlas to add a `suite` and `check` block from `std/unittest` under your `tests/` directory. Atlas can then run `nimble test` to verify the new tests, provided permissions are pre-approved.

How do I get structured output from Atlas for parsing in a Nim CI script?

Invoke `atlas run` with the `--format json` flag. This streams raw event data to stdout, which can be easily parsed by a Nim script or other CI tools to process Atlas's actions and results.

What if an Atlas session needs to continue work from a previous Nim CI run?

You can resume or fork a prior Atlas session using the `--continue`, `--session`, or `--fork` flags with `atlas run`. This allows subsequent CI steps to build upon or re-evaluate work from an earlier run.

Does Atlas understand my Nim project's structure, like `.nimble` files?

Yes, Atlas reads your `nimble` package's `.nimble` file, understanding modules, exported symbols marked with an asterisk, and `requires` lines to build its code index and context.

Run Atlas Headless in CI for Nim Projects in 2026

Nim developers in 2026 can run Atlas sessions non-interactively in CI pipelines to get machine-readable output by invoking `atlas run` with the `--format json` flag, enabling direct integration with `nimble` projects and their existing `nimble test` and `nph` toolchain.

How to Run Atlas Headless in Nim CI Pipelines for Automated Tasks

To run Atlas non-interactively in a Nim CI pipeline, developers in 2026 use the `atlas run` command, passing a single prompt and specifying `--format json` to receive machine-readable output. This approach ensures that automated steps can parse Atlas's event stream, making it ideal for tasks like adding a new `unittest` suite to a `nimble` package.

The `atlas run` command is specifically designed for non-interactive execution, making it perfect for CI environments. By default, it accepts a single prompt, streams events to standard output, and then exits once the session becomes idle. For Nim CI pipelines that require programmatic interaction, the `--format json` flag is essential. This flag instructs Atlas to output raw event data in a structured JSON format, rather than human-readable prose. This machine-readable stream allows subsequent pipeline steps to easily parse Atlas's actions, such as code modifications or test results, enabling robust automation for your `nimble` projects. When running headless, it is also crucial to explicitly set the model using the `provider/model` form, for example, `github/copilot-gpt4`, as generic model names are rejected in this context.

Managing Tool Permissions for Unattended Nim Codebase Edits

For Atlas to operate autonomously within a Nim CI pipeline, all necessary tools must be pre-approved in the permission configuration, as there is no interactive user to respond to `ask` prompts. This ensures Atlas can execute actions like `edit` or `bash` commands on your `nimble` project without interruption, a critical step for 24/7 automation.

Atlas employs a robust permission-gating system for every tool call, with `allow`, `ask`, and `deny` rules. In a headless CI environment, the `ask` prompt cannot be answered, making pre-approval of tools mandatory for any operation that modifies the codebase or interacts with the system. For typical Nim development tasks, Atlas will utilize tools such as `bash` for executing shell commands, `read` for accessing file contents, `edit` for making code changes, and `todowrite` for managing tasks. Before deploying Atlas in your Nim CI, ensure these essential tools are explicitly set to `allow` in your Atlas permission configuration. This proactive setup guarantees that Atlas can perform its duties, like adding a `unittest` suite or formatting code with `nph`, without requiring manual intervention.

direct Integration with Nimble, Nimble Test, and NPH in CI

Atlas integrates deeply with the Nim toolchain, recognizing `nimble` packages and their `.nimble` files to understand project structure. In 2026, Atlas can be instructed to add a `std/unittest` suite, run `nimble test` to validate changes, and then format touched modules using `nph`, all within a single automated CI run.

Atlas is designed to work natively within the Nim ecosystem. It intelligently reads your `nimble` package's `.nimble` file, parsing module definitions, exported symbols marked with an asterisk, and `requires` lines to build a comprehensive understanding of your project's structure. This deep understanding allows Atlas to perform highly relevant actions. For instance, you can prompt Atlas to add a new `suite` and `check` block from Nim's `std/unittest` module under your `tests/` directory. After making modifications, Atlas can then execute `nimble test` to validate the changes, provided this action is pre-approved in the permissions. Furthermore, Atlas can be instructed to format any touched Nim modules using `nph`, ensuring code consistency and adherence to style guidelines across your `nimble` project. This integration ensures that Atlas operates as a natural extension of your existing Nim development workflow.

Iterative Development and Session Management in Nim CI

Nim developers can manage complex, multi-step CI workflows by resuming or forking prior Atlas sessions using `--continue`, `--session`, or `--fork`. This capability allows a pipeline step to build upon an earlier run, for instance, if an initial Atlas session in 2026 failed a `nimble test` and requires a follow-up fix.

For advanced CI workflows or debugging scenarios in Nim projects, Atlas provides powerful session management capabilities. The `--continue` flag allows you to resume a previous Atlas session, picking up exactly where it left off. This is invaluable if a CI job was interrupted or if you need to iterate on a problem that Atlas was addressing. Similarly, the `--session` flag lets you specify a particular session ID to work with, enabling you to replay or inspect past runs. The `--fork` option allows you to create a new session based on an existing one, providing a clean slate while retaining the context and history of the original. These features are particularly useful when Atlas needs to perform multi-stage tasks, such as fixing a bug identified by `nimble test` in an earlier CI run, then adding a new feature, and finally ensuring all changes are formatted correctly with `nph`.

Parsing Machine-Readable Output from Atlas in Nim CI

When `atlas run` is invoked with `--format json`, it streams raw event data to stdout, providing a machine-readable output crucial for subsequent pipeline steps. This structured data, available in 2026, allows Nim CI scripts to programmatically parse Atlas's actions, such as file edits or `nimble test` results, for automated reporting or conditional logic.

The `--format json` flag transforms Atlas's output from human-readable prose into a stream of structured JSON events. This is the cornerstone for integrating Atlas into automated Nim CI pipelines. Each event in the stream represents a specific action or state change within the Atlas session, such as a tool call, a plan draft, a file edit, or the result of a `bash` command like `nimble test`. A Nim script or any CI orchestration tool can consume this JSON stream, parse individual events, and react accordingly. For example, a pipeline step could check for `edit` events to verify code modifications, or parse the output of a `nimble test` run to determine if all tests passed. This programmatic access to Atlas's internal workings enables sophisticated automation, allowing you to build custom reporting, trigger subsequent actions, or implement conditional logic based on Atlas's performance in your Nim codebase.

Step by step

01Prepare your Nim project by ensuring a `.nimble` file is present and Atlas can access your modules and dependencies.
02Configure Atlas permissions by pre-approving `bash`, `read`, `edit`, and `todowrite` tools in Atlas's permission configuration for unattended execution on your Nim codebase.
03Invoke Atlas headless with a Nim-specific prompt, for example: `atlas run --format json --model github/copilot-gpt4 "Add a new `check` block to `tests/my_module_test.nim` using `std/unittest` to verify the `myFunction` export in `src/my_module.nim`."`
04Parse Atlas's machine-readable JSON event stream from `stdout` using a Nim script or CI tool to analyze Atlas's actions, such as `edit` operations or `nimble test` outcomes.
05Review and commit changes: If Atlas proposes changes, such as adding a `unittest` suite or formatting with `nph`, review the generated git diffs and stage/commit them using `git commit -m "feat: Atlas added unittest for myFunction"` or similar.
06Optionally resume a session for further iteration: If additional work is needed, use `atlas run --continue <session_id> --format json "Fix the `nimble test` failures in `tests/my_module_test.nim`."`

Frequently asked questions

How do I run Atlas in a Nim CI pipeline without user interaction?: You run `atlas run` with your prompt and the `--format json` flag. This executes Atlas non-interactively, streaming machine-readable events to stdout, and exits when the session goes idle.
What Nim-specific tools does Atlas integrate with in CI?: Atlas integrates with the `nimble` package manager, the `nimble test` runner for unit tests, and the `nph` formatter, allowing it to understand, modify, and validate Nim code.
How does Atlas handle permissions for file edits in a headless Nim CI environment?: For headless runs, all Atlas tools like `edit` and `bash` must be pre-approved in the permission configuration. This bypasses interactive `ask` prompts, ensuring uninterrupted execution in your Nim CI.
Can Atlas help me add unit tests to my Nim project in CI?: Yes, you can prompt Atlas to add a `suite` and `check` block from `std/unittest` under your `tests/` directory. Atlas can then run `nimble test` to verify the new tests, provided permissions are pre-approved.
How do I get structured output from Atlas for parsing in a Nim CI script?: Invoke `atlas run` with the `--format json` flag. This streams raw event data to stdout, which can be easily parsed by a Nim script or other CI tools to process Atlas's actions and results.
What if an Atlas session needs to continue work from a previous Nim CI run?: You can resume or fork a prior Atlas session using the `--continue`, `--session`, or `--fork` flags with `atlas run`. This allows subsequent CI steps to build upon or re-evaluate work from an earlier run.
Does Atlas understand my Nim project's structure, like `.nimble` files?: Yes, Atlas reads your `nimble` package's `.nimble` file, understanding modules, exported symbols marked with an asterisk, and `requires` lines to build its code index and context.

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 Nim: A Terminal-Native AI Coding Agent for Nimble Packages and Macros in 2026

Atlas is a terminal-native AI coding agent for Nim in 2026. It reads .nimble requires and asterisk-exported symbols, adds std/unittest suites, runs nimble test, formats with nph.

Locate where a behavior is implemented in Nim with Atlas in 2026

In 2026, Nim developers use Atlas to pinpoint behavior implementations. Atlas combines semantic search, `grep`, and LSP tools to quickly find exact files and symbols within `nimble` projects, ensuring precise code

Upgrade a dependency and fix the breakage in Nim with Atlas in 2026

Nim developers in 2026 can use Atlas to direct upgrade dependencies, fixing compile and test failures. Atlas integrates with nimble, nph, and unittest.

Research a third-party API before integrating it in Nim with Atlas in 2026

Nim developers in 2026 use Atlas to efficiently research third-party APIs. Learn how Atlas leverages websearch and webfetch to get current API shapes, ensuring accurate integrations in your Nim projects.

Debug a single failing test in Nim with Atlas in 2026

In 2026, Nim developers use Atlas to efficiently debug failing tests. Learn how Atlas leverages `nimble test`, `lsp`, and `nph` to pinpoint and fix issues in your Nim codebase.

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

Efficiently migrate deprecated Nim APIs across your entire codebase in 2026 using Atlas. Ensure every callsite is updated with the replacement, leveraging Nim's `nimble test` and `nph` for verification and formatting.

Onboard to an unfamiliar codebase in Nim with Atlas in 2026

Quickly build a mental model of any Nim codebase in 2026 using Atlas. Leverage nimble, nph, and semantic search to understand new projects without reading every file.

Browse this resource hub