> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arc.computer/llms.txt
> Use this file to discover all available pages before exploring further.

# Atlas CLI Reference

> Command catalogue for discovery, configuration scaffolding, and runtime execution in the Atlas SDK.

The Atlas CLI packages everything ML engineers need to onboard a new environment, validate a stack, and ship telemetry
into the learning pipeline—without writing glue code. Commands are grouped under the `atlas` executable (installed with
`arc-atlas`) and the `arc-atlas` helper for export/review automation. The CLI automatically loads `.env` files from the
project root and extends `PYTHONPATH` with `src`/root directories.

| Workflow                 | Command(s)                                 | Summary                                                                   |
| ------------------------ | ------------------------------------------ | ------------------------------------------------------------------------- |
| Autodiscovery onboarding | `atlas env init`, `atlas env scaffold`     | Detect agent/environment pairs, synthesize factories, and cache metadata. |
| Runtime execution        | `atlas run`, `atlas run --config`          | Replay discovery output or run a full orchestrator config.                |
| Persistence bootstrap    | `atlas init`                               | Provision Postgres via Docker (optional).                                 |
| Review & export          | `arc-atlas review …`, `arc-atlas export …` | Gate traces behind human review and export approved sessions.             |
| Training handoff         | `atlas train`                              | Reuse exporter filters and launch Atlas Core pipelines.                   |

## Environment Discovery

### `atlas env init`

Discovers agents/environments and populates `.atlas/`. Uses Claude Haiku 4.5 for agent ranking (auto-selects at 0.85+ confidence).

Key flags: `--task`, `--scaffold-config-full`, `--no-run`, `--timeout` (240s default)

Outputs: `.atlas/discover.json`, `.atlas/generated_config.yaml`, `.atlas/runs/`

### `atlas env scaffold`

Seeds projects with reference factories (LangGraph template). Use `--template`, `--output`, `--force` flags. Follow with `atlas env init` to validate.

## Runtime Execution

### `atlas run`

Executes a discovered agent/environment pair using cached metadata.

* `--task` (required) – prompt to execute.
* `--path` – project root containing `.atlas/discover.json`.
* `--env KEY=value` – additional environment variables surfaced to the runtime worker.
* `--mode` – experimental execution-mode override (`auto`, `paired`, etc.) used for deterministic tests.
* `--max-steps` – informational cap for orchestration steps (helpful during debugging).
* `--timeout` – worker timeout (default 300 s).

Before launching, the CLI verifies module hashes, loads the latest learning playbooks (when enabled), and streams
metadata snapshots to `.atlas/runs/`.

### `atlas run --config`

When you provide `--config path/to/runtime.yaml`, the CLI bypasses discovery metadata and spins up the full orchestrator
stack defined in the YAML. This mode:

* loads the config via `atlas.config.loader`,
* enables validation caching and telemetry instrumentation from PR #74,
* respects the same environment-variable injection and task prompt flags,
* captures the full `ExecutionContext` metadata (steps, learning state, reward payloads) and writes it to `.atlas/runs/`
  alongside the config path, letting you correlate later exports with the exact settings that produced them.

Use this path when running orchestrator smoke tests, CI checks, or scripted experiments against a fixed configuration.

## Review & Safety Workflow

Atlas gates trace exports behind review status to keep production learning safe. Review utilities live behind the
`arc-atlas` entrypoint (same binary as `python -m atlas.cli.export`).

### `arc-atlas review`

Manage session approvals stored in Postgres:

* **List sessions**
  ```bash theme={null}
  arc-atlas review sessions --database-url postgresql://atlas:atlas@localhost:5433/atlas --status pending --limit 50
  ```
  Groups by review status (defaults to pending/quarantined/approved). Use `--limit`/`--offset` to page through results.

* **Approve**
  ```bash theme={null}
  arc-atlas review approve 123 --database-url ... --note "Validated in staging"
  ```

* **Quarantine**
  ```bash theme={null}
  arc-atlas review quarantine 456 --database-url ... --note "Reward regression"
  ```

All review commands honour `--quiet` to suppress info logs. For local development you can bypass the gate with
`ATLAS_REVIEW_REQUIRE_APPROVAL=0`, but production exports should always run through the review queue.

### Drift & Safety Flags

* `runtime_safety.drift` in the config enables z-score based drift detection; alerts surface in the review output.
* `runtime_safety.review.require_approval` (default `true`) controls export gating; changing it requires a config update
  or environment override (`ATLAS_REVIEW_REQUIRE_APPROVAL=0`).

## Exporting & Training

### `arc-atlas export`

Exports approved sessions to JSONL for training or offline analysis.

* `--database-url` – required Postgres connection.
* `--output` – destination file (default: `<atlas-core-path>/exports/<timestamp>.jsonl` when `atlas-core-path` is known).
* `--session-id` – explicit session IDs (repeatable).
* `--limit`/`--offset` – pagination for recent sessions.
* `--status` – runtime completion status filter (`succeeded`, `failed`, etc.).
* `--trajectory-event-limit` – cap telemetry per session.
* `--include-status approved` – allow additional review statuses; `--include-all-statuses` bypasses the gate entirely.
* `--batch-size` – database fetch chunk size.

If no sessions are exported, the CLI reminds you to approve pending sessions first. Output JSON matches the schema
documented in [`Export Runtime Traces`](/sdk/export-traces).

### `atlas train`

Bridges exports into Atlas Core’s offline pipeline. It reuses the exporter filters above and then launches
`atlas-core offline-pipeline` with Hydra overrides.

* Filters: `--session-id`, `--limit`, `--status`, `--include-status`, `--trajectory-event-limit`.
* Atlas Core overrides: `--atlas-core-path`, `--config-name`, `--data-config`, `--trainer-config`, `--model-config`.
* Dataset sampling: `--eval-ratio`, `--max-samples`, `--use-sample-dataset`.
* Execution control: `--dry-run` prints the derived command without launching.
* Tracking: `--wandb-project`, `--wandb-run-name`, and repeatable `--override` flags.

Run `atlas train` once Postgres contains a critical mass of approved sessions. For ad-hoc exports, stick with
`arc-atlas export`.

## Storage & Bootstrap Utilities

* **`atlas init`** – writes `atlas-postgres.yaml` (Docker Compose) to spin up the recommended Postgres instance. Use
  `--force` to overwrite or `--skip-docker-install` if Docker is already available.
* **`atlas quit`** – tears down storage resources created by `atlas init`.

## Environment & Troubleshooting Tips

* **`.env` loading** – All CLI entrypoints call `load_dotenv_if_available()`; keep provider keys, database URLs, and
  custom environment variables there.
* **PYTHONPATH** – `atlas env init` adds the project root and `src/` directory to `PYTHONPATH`, making local packages
  importable without manual exports.
* **Timeouts** – Adjust `--timeout` per command when hitting slower providers or complex factory initialization.
* **Logging** – Most commands support `--quiet`; otherwise logs stream to stdout with timestamps.

## Related Guides

* [`SDK Quickstart`](/sdk/quickstart) – end-to-end walkthrough using these commands.
* [`Learning System Architecture`](/sdk/learning-system) – how CLI telemetry feeds runtime learning.
* [`Installation`](/installation) – environment prerequisites and GPU-aware setup.
* [`Export Runtime Traces`](/sdk/export-traces) – JSON schema and downstream training integration.