# Run Atlas Headless in CI with PowerShell in 2026 > Run Atlas headless in PowerShell CI by invoking `atlas run --format json` to get machine-readable output for automated pipeline steps. To run an Atlas session non-interactively in a PowerShell pipeline and retrieve machine-readable output, invoke `atlas run` with the `--format json` flag, ensuring your `Pester` tests and `PSResourceGet` dependencies are managed. This approach allows Atlas to stream events to stdout, which can then be parsed by subsequent PowerShell steps for automated analysis and decision-making, integrating direct with your existing PowerShell toolchain. ## Key takeaways - Use `atlas run --format json` to get machine-readable output for PowerShell pipelines. - Pre-approve Atlas tools like `bash`, `read`, `edit`, and `todowrite` for headless PowerShell CI. - Atlas integrates with `Pester` for testing and `PSScriptAnalyzer Invoke-Formatter` for PowerShell code quality. - Manage Atlas sessions in PowerShell CI using `--continue`, `--session`, or `--fork` for continuity. - Atlas reads PowerShell modules (`.psm1`) and manifests (`.psd1`) for comprehensive code context. ## How to run Atlas headless in PowerShell CI pipelines? To run Atlas headless in PowerShell CI pipelines, invoke `atlas run` with the `--format json` flag. This enables non-interactive execution, streaming machine-readable events to stdout for automated processing in your 2026 CI/CD workflows. The default mode sends a single prompt and exits when idle. Running Atlas headless in a PowerShell CI pipeline is achieved by using the `atlas run` command. This command is specifically designed for non-interactive environments, sending a single prompt to Atlas and then exiting once the session goes idle. For automated processing within your PowerShell scripts, the `--format json` flag is essential. This flag instructs Atlas to stream all session events to stdout as raw JSON, rather than human-readable prose. A PowerShell script can then capture this output, for example, by piping it to `ConvertFrom-Json`, allowing subsequent pipeline steps to programmatically parse Atlas's actions, observations, and proposed changes. This ensures that your CI system can make automated decisions based on Atlas's output, such as approving a code change, triggering `Pester` tests, or running `PSScriptAnalyzer Invoke-Formatter`. ## How to configure Atlas permissions for headless PowerShell automation? To configure Atlas permissions for headless PowerShell automation, pre-approve tools like `bash`, `read`, `edit`, and `todowrite` in your Atlas configuration. This is critical because a headless run has no human to answer `ask` prompts, ensuring your 4 essential tools execute without interruption. In a headless PowerShell CI environment, Atlas operates without human intervention, meaning there is no opportunity to respond to `ask` prompts for tool execution. Therefore, it is crucial to pre-approve all tools that Atlas might need to use during its session. Atlas's permission configuration allows you to set `allow`, `ask`, or `deny` rules for each tool. For a headless run, any tool Atlas needs to use, such as `bash` for executing shell commands, `read` for accessing file content, `edit` for modifying files, or `todowrite` for creating new files, must be explicitly set to `allow`. This ensures that Atlas can perform its tasks, like modifying a `.psm1` module or writing a `.Tests.ps1` file, without pausing the CI pipeline to wait for a non-existent approval. Properly configured permissions are a cornerstone of secure and efficient headless automation with Atlas in PowerShell. ## How to integrate Atlas with PowerShell testing and formatting? Integrating Atlas with PowerShell testing and formatting involves leveraging `Pester` and `PSScriptAnalyzer Invoke-Formatter`. Atlas can write `.Tests.ps1` files and run `Invoke-Pester` behind a permission prompt, ensuring your PowerShell modules meet quality standards in 2026. Atlas is designed to integrate deeply with the PowerShell toolchain, enhancing both testing and code formatting within your CI pipelines. When working with PowerShell code, Atlas can be instructed to generate and write `.Tests.ps1` files, which are the standard for `Pester` test suites. After generating tests or making code changes, Atlas can then run `Invoke-Pester` to validate the modifications. This execution of `Invoke-Pester` is permission-gated, meaning Atlas will seek approval before running the tests, even in a headless context if configured to `ask` (though `allow` is preferred for full automation). Furthermore, Atlas can assist with code quality by clearing `PSScriptAnalyzer` warnings and running `PSScriptAnalyzer Invoke-Formatter` over any diffs it proposes. This ensures that your PowerShell modules, advanced functions, and scripts maintain consistent style and adhere to best practices, all orchestrated by Atlas within your CI workflow. ## How to manage Atlas sessions and models in PowerShell CI? Managing Atlas sessions and models in PowerShell CI is achieved using flags like `--continue`, `--session`, or `--fork`. This allows a pipeline step to resume or replay a prior session, ensuring continuity across multiple CI stages in 2026, even for complex 10-step workflows. For advanced CI workflows in PowerShell, Atlas provides robust session management capabilities. The `--continue` flag allows a new `atlas run` invocation to pick up where a previous session left off, building on its context and progress. Alternatively, `--session ` can be used to explicitly resume a specific prior session, which is useful for replaying or debugging a particular step in a multi-stage pipeline. The `--fork` option creates a new session based on an existing one, allowing for parallel experimentation or alternative approaches without altering the original session's state. for model selection, it is critical to set the model explicitly using the `provider/model` form, for example, `github/copilot-gpt4`. Atlas strictly enforces this format, rejecting any other input. This ensures that your headless PowerShell CI jobs consistently use the intended AI model for their tasks, leveraging Atlas's ability to switch active models and providers on the fly. ## Steps 1. Prepare Atlas configuration for PowerShell: Ensure Atlas is configured in the directory containing your `.psm1` module and `.psd1` manifest. Pre-approve necessary tools like `bash`, `read`, `edit`, and `todowrite` in Atlas's permission configuration to enable headless operations. 2. Invoke Atlas headless with a prompt: Execute `atlas run --format json "Add CmdletBinding and SupportsShouldProcess to New-ItemFunction.ps1"` from your PowerShell script. This sends a single prompt and streams machine-readable JSON events to stdout. 3. Capture and parse Atlas output in PowerShell: Use PowerShell's `ConvertFrom-Json` cmdlet to parse the streamed JSON output from `atlas run`. For example: `atlas run --format json "..." | ConvertFrom-Json`. This allows subsequent PowerShell steps to programmatically analyze Atlas's actions and results. 4. Automate PowerShell code quality checks with Atlas: After Atlas makes edits, have it clear `PSScriptAnalyzer` warnings and run `PSScriptAnalyzer Invoke-Formatter` over the diff. This can be achieved by prompting Atlas to perform these actions or by integrating `PSScriptAnalyzer Invoke-Formatter` as a post-Atlas step in your PowerShell script. 5. Validate changes with Pester tests: Instruct Atlas to write `.Tests.ps1` files and then run `Invoke-Pester` to validate the changes. This can be done by prompting Atlas to 'Write Pester tests for New-ItemFunction.ps1 and run them' or by integrating `Invoke-Pester` as a post-Atlas step in your PowerShell script. 6. Commit changes with Atlas (permission-gated): If Atlas's edits and tests pass, allow Atlas to stage and create commits. This is permission-gated, ensuring approval before writing. For example, `atlas run --command "/commit"` after successful validation, assuming `/commit` is an exposed command. ## FAQ ### How do I get machine-readable output from Atlas in a PowerShell script? Invoke `atlas run` with the `--format json` flag. The event stream will be sent to stdout as JSON, which you can capture and parse using PowerShell's `ConvertFrom-Json` cmdlet for automated processing. ### Can Atlas run Pester tests in a CI pipeline? Yes, Atlas can be prompted to write `.Tests.ps1` files and run `Invoke-Pester` behind a permission prompt. This ensures your PowerShell modules are validated against their test suites. ### How do I ensure Atlas doesn't prompt for permissions in a headless PowerShell CI job? Pre-approve all necessary tools, such as `bash`, `read`, `edit`, and `todowrite`, in Atlas's permission configuration. Headless runs cannot respond to `ask` prompts, so `allow` rules are essential. ### What PowerShell files does Atlas understand for context? Atlas reads your `.psm1` module files, `.psd1` manifest files, exported cmdlets, and parameter blocks to build its code index using AST declarations, providing deep contextual understanding. ### How can Atlas help with PowerShell code formatting in CI? Atlas can clear `PSScriptAnalyzer` warnings and run `PSScriptAnalyzer Invoke-Formatter` over the diffs it proposes, ensuring your PowerShell code adheres to style guidelines automatically within your CI pipeline. ### Can I resume an Atlas session in a subsequent PowerShell CI step? Yes, use `atlas run --continue` or `atlas run --session ` to resume a prior session. This allows a pipeline step to build on or replay an earlier Atlas run, maintaining context. ### How do I specify the model for Atlas in a headless PowerShell CI environment? Set the model explicitly using the `provider/model` form, for example, `atlas run --model github/copilot-gpt4 "..."`. This specific format is required and rejects any other input. --- Canonical HTML: https://runatlas.sh/resources/stacks/run-atlas-headless-in-ci-in-powershell Source of truth: aeo_pages row `/resources/stacks/run-atlas-headless-in-ci-in-powershell` (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.