# Atmos Pro

Atmos CLI handles the execution layer — how you architect your cloud infrastructure, run automation
reproducibly across local and CI, and manage authentication. Atmos Pro is the control plane above
that, giving you visibility and coordination across all your teams, repositories, and environments.

## Why Atmos Pro?

**Atmos CLI** solves the problems every company encounters: structuring Terraform at scale, running
the same automation locally and in CI, handling auth, installing toolchains, managing component
dependencies, keeping configuration DRY with inheritance and templating, and vendoring components
across repositories. It owns the execution layer — plan, apply, deploy.

**Atmos Pro** solves what happens when you scale that up. Multiple repositories, multiple GitHub
organizations, dozens of teams, hundreds of components. You need to know what changed, what's
drifting, what's failing, who approved what, and what the current state of every deployment is —
across everything.

Because Atmos CLI already handles execution, Atmos Pro doesn't need elevated access to your cloud
accounts. It receives what the CLI uploads — affected stacks, component inventories, plan results —
and gives you the coordination layer on top:

- **Visibility** — See what's affected on every PR, across every repo and organization
- **Drift detection** — Know which stacks have drifted and trigger remediation automatically
- **Approvals and change requests** — Coordinate who can apply what, with full audit trails
- **Failing runs** — Stay on top of failures across all teams without digging through CI logs
- **Stack locking** — Prevent concurrent modifications during deployments
- **Inventory** — Understand what's deployed, where, and with what configuration

## Quick Start

### 1. Configure Your Workspace

**File:** `atmos.yaml`

```yaml
settings:
  pro:
    workspace_id: "your-workspace-id"
```

### 2. Add Workflow Permissions

**File:** `.github/workflows/atmos.yaml`

```yaml
permissions:
  id-token: write   # Required for OIDC token exchange with Atmos Pro
  contents: read
```

### 3. Upload Affected Stacks from Your Workflow

**File:** `.github/workflows/atmos.yaml`

```yaml
jobs:
  affected:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Upload affected stacks
        run: atmos describe affected --upload
```

**Pro Configuration**

Configure workspace ID, authentication, payload chunking, and drift detection in your `atmos.yaml`.

Configuration Reference[Read more](/cli/configuration/settings/pro)

## Authentication

Atmos Pro uses **GitHub OIDC token exchange** for authentication. No API keys or static credentials
are needed. When running in GitHub Actions with `id-token: write` permission, Atmos automatically
requests an OIDC token and exchanges it for a short-lived Atmos Pro bearer token.

The only configuration required is your `workspace_id`, which identifies your organization's
workspace. This value is not a secret and is safe to commit to version control.

**File:** `atmos.yaml`

```yaml
settings:
  pro:
    workspace_id: "your-workspace-id"
```

## Features

### Affected Stacks

Upload the results of `atmos describe affected` to Atmos Pro for visibility into what changed
on each pull request. Atmos Pro correlates uploads with GitHub webhooks to show affected
components directly in your PR workflow.

```shell
atmos describe affected --upload
```

### Component Instances

Upload a complete inventory of all component instances across all stacks. Atmos Pro uses this
to track what is deployed, where, and with what settings — across every repository in your
organization.

```shell
atmos list instances --upload
```

### Stack Locking

Prevent concurrent modifications to the same stack. Lock before apply, unlock after — Atmos Pro
tracks who holds the lock and when it was acquired.

```shell
atmos pro lock vpc -s prod-use1
atmos terraform apply vpc -s prod-use1
atmos pro unlock vpc -s prod-use1
```

### Drift Detection

Track Terraform plan results to detect infrastructure drift. When `--upload-status` is enabled,
Atmos uploads the plan exit code so Atmos Pro can identify stacks that have drifted from their
desired state and trigger remediation workflows.

```shell
atmos terraform plan vpc -s prod-use1 --upload-status
```

## Commands

- **[`atmos describe affected --upload`](/cli/commands/describe/affected)**
  Upload affected components and stacks to Atmos Pro for PR correlation.
- **[`atmos list instances --upload`](/cli/commands/list/list-instances)**
  Upload a complete inventory of component instances to Atmos Pro.
- **[`atmos pro lock`](/cli/commands/pro/lock)**
  Lock a stack to prevent concurrent modifications.
- **[`atmos pro unlock`](/cli/commands/pro/unlock)**
  Unlock a previously locked stack.
- **[`atmos terraform plan --upload-status`](/cli/commands/terraform/plan)**
  Upload plan results for drift detection.

## Environment Variables

- **`ATMOS_PRO_WORKSPACE_ID`**
  Workspace identifier for OIDC authentication. Not a secret. Maps to 
  `settings.pro.workspace_id`
  .
- **`ATMOS_PRO_BASE_URL`**
  Override the Atmos Pro API base URL. Maps to 
  `settings.pro.base_url`
  .
- **`ATMOS_PRO_ENDPOINT`**
  Override the API endpoint path. Maps to 
  `settings.pro.endpoint`
  .
- **`ATMOS_PRO_TOKEN`**
  Internal runtime token from OIDC exchange (advanced/internal). Do not set this manually; configure 
  `settings.pro.workspace_id`
   and GitHub Actions 
  `id-token: write`
   instead.

## Troubleshooting

### OIDC Authentication Failures

If `--upload` fails with an authentication error:

1. Verify your workflow has `id-token: write` permission
2. Confirm `ATMOS_PRO_WORKSPACE_ID` is set to the correct workspace
3. Check that the Atmos Pro GitHub App is installed on your repository

### Upload Access Denied (403)

If the upload succeeds authentication but returns a 403:

1. Verify the repository has been imported into your Atmos Pro workspace
2. Check repository permissions in your Atmos Pro workspace settings

## Related

- [Pro Configuration](/cli/configuration/settings/pro) - Full configuration reference for `settings.pro`
- [Auth](/stacks/auth) - Configure OIDC authentication
- [Native CI](/ci) - CI/CD integration for GitHub Actions