Getting started

Atlas Commands

Reference guide for all Atlas CLI commands and flags.

Atlas CLI Commands#

All commands are invoked as atlas <command> [flags].
Run atlas --help for a full list at any time.

`atlas`#

The core command to analyze, build, fix, run tests, and deploy a project.

atlas [path] [flags]

Flags#

Flag	Description
`--path <path>`	Project path (alternative to positional arg, use this for paths that collide with a subcommand name)
`--dir <path>`	Target subdirectory within a monorepo (e.g. `apps/web`)
`--workspace <name>`	Target package name within a monorepo (e.g. `web` or `@myorg/web`)
`--model <name>`	LLM provider to use (e.g., `anthropic`, `openai`) (optional)
`--action <mode>`	Action mode: `build`, `test`, `deploy`, `test-and-deploy` (optional)
`--provider <name>`	Deployment provider: `vercel`, `render`, `netlify` (optional; `fly` and `railway` are planned for v0.3.0)
`--output-dir <path>`	Manually specify the static output directory for deployment (optional)
`--allow-dirty`	Skip the uncommitted-changes check and proceed anyway
`--auto-rollback-on-unhealthy`	Automatically rollback without prompting if post-deploy health check fails
`--strict-env`	Abort deployment if any required environment variables are missing from local environment or .env files
`--yes`, `-y`, `--non-interactive`	Auto-approve deployment and run non-interactively without prompting
`--json`	Output in machine-readable JSON format and suppress interactive prompts

Interactive Wizard
Running atlas <path> without all required flags will launch an interactive terminal wizard to guide you through selecting a model, picking an action, and setting credentials.

Path Collision Caveat
If your project directory shares a name with a registered subcommand (like models, providers, debug), atlas <that-name> will run the subcommand, not treat it as a path. Use the --path <that-name> escape hatch to disambiguate.

Examples#

Run a complete deployment pipeline silently by providing all flags:

$ atlas ./oss/todo --model anthropic --action deploy --provider vercel
✓ Config loaded
✓ Workspace resolved
→ Checking Vercel authentication...
✓ Vercel authenticated (cli_session, you@example.com)
✓ Session created (sess_4881adb76fe6adb0)
✓ Project analyzed → framework: react, package_manager: npm
✓ Git validated → is_clean:true
✓ Build succeeded (12.3s) → dist/
→ Awaiting approval to deploy to vercel (production) [y/N]: y
→ Deploying to vercel (production)...
✓ Deployed successfully to https://my-app-xyz.vercel.app

`atlas providers`#

Manage and view authentication status for all supported deploy providers. Pass --json to output authentication metadata in machine-readable JSON format without exposing secrets.

atlas providers [flags]

Flags#

Flag	Description
`--json`	Output provider credential metadata as JSON

Example Output:

$ atlas providers
DEPLOY PROVIDERS
  vercel     ✓ authenticated   (cli_session, you@example.com, verified 2026-07-13 10:02:00)
  render     ✗ not configured

Subcommands#

Securely store a deployment provider token in your OS keychain.

$ atlas providers set vercel
Vercel token: ████████████████████████████
✓ Stored. This will be used instead of the CLI-delegated login next time you deploy.

Security Note: Secret values are never printed to the console — only detected, authenticated, or not configured status. Vercel and Render will check their respective env vars (VERCEL_TOKEN, RENDER_TOKEN) before falling back to the credential store.

`atlas models`#

Manage and view API key status for all supported LLM providers.

atlas models

Example Output:

$ atlas models
LLM MODELS   (active: mistral-large-latest — from config.json's default_model)
  anthropic  ✓ stored (claude-3-5-sonnet-20240620)
  openai     ✗ OPENAI_API_KEY not set (gpt-4o)
  gemini     ✗ GEMINI_API_KEY not set (gemini-1.5-pro)

Subcommands#

Securely store an LLM API key.

$ atlas models set anthropic
API key for anthropic: ████████████████████████████
✓ Stored. Run `atlas models` to confirm.

The active: label comes from .atlas/config.json's llm_provider field in the current directory. Only environment variable presence is checked here; use atlas testllm to verify the key actually works.

`atlas testllm`#

Send a small ping to the configured LLM to verify the API key is active and successfully authenticated.

atlas testllm <path>

$ atlas testllm .
Testing LLM connection to provider: mistral (model: mistral-large-latest)...
LLM Response: SUCCESS
✓ API key is active and connection is working!

`atlas status`#

Show the status and pipeline progress of the latest or a specified Atlas deployment session. It also performs a live health check on the deployment URL if available.

atlas status [session] [flags]

Flags#

Flag	Description
`--session <uuid>`	Specific session UUID to check (default: latest)
`--json`	Output status as JSON

Example Output:

$ atlas status
Atlas Status
Session: sess_1234abcd
Status:  Done
Started: 2 mins ago

Pipeline Progress
 ✓ Analyze Project
 ✓ Build Project (Success, 1250ms)
 ✓ Deploy Project

Deployment
  Provider: vercel
  URL:      https://my-app-xyz.vercel.app
  Health:   Up (200 OK)

`atlas doctor`#

Run comprehensive diagnostics on installed developer tools, security credentials, LLM API connectivity, and Atlas release freshness.

atlas doctor [path] [flags]

Flags#

Flag	Description
`--json`	Output diagnostic report in machine-readable JSON format

Diagnostic Categories#

Tools & Environment: Inspects Git (version, clean/dirty working tree state), Node.js, npm, pnpm, yarn, bun, Go, Python, and Docker daemon reachability.
Security & Credentials: Verifies OS keychain accessibility (native OS keychain vs 0600 fallback file) and authenticated deployment providers.
LLM Configuration: Inspects configured provider and model, and measures live API completion ping latency.
Atlas Version: Compares running version with the latest GitHub release.

$ atlas doctor

 ATLAS DOCTOR 

Tools & Environment
  ✓ Git                git version 2.43.0 (clean working tree)
  ✓ Node               v24.19.0
  ✓ Npm                12.2.0
  ✓ Pnpm               12.9.1
  ✓ Bun                1.3.13
  ✓ Go                 go version go1.27.1
  ✓ Docker             Docker version 28.1.1 (daemon reachable)

Security & Credentials
  ✓ Keyring            Native OS keychain available
  ✓ Vercel             Authenticated (cli_session)
  ✓ Render             Authenticated via RENDER_TOKEN
  ✓ Netlify            Authenticated (cli_session)

LLM Configuration
  ✓ Model (claude-3-5-sonnet-20240620) Connected (latency: 340ms)

Atlas Version
  ✓ Atlas CLI          v0.2.0 (Up to date with latest release)

╭───────────────────────────────────────────────────╮
│  ✓ All diagnostic checks passed! Atlas is ready.  │
╰───────────────────────────────────────────────────╯

`atlas audit`#

Scan templates (.env.example, .env.sample, .env.template, and .env.local.example) and source code (process.env, os.environ, os.Getenv) for required environment variables and verify their configuration status.

atlas audit [path] [flags]

Flags#

Flag	Description
`--provider <name>`	Target deployment provider (remote key sync planned for v0.3.0)
`--strict`	Exit with code 1 if any missing environment variables are discovered
`--dir <path>`	Target a specific subdirectory within a monorepo
`--workspace <name>`	Target a specific package by name in a monorepo
`--json`	Output machine-readable JSON containing the `SecretAuditReport`

Zero Secret Leaks & Strict Verification
Atlas reads local environment configurations only to verify key presence and non-empty status; secret values are never printed, stored, or exposed in audit reports. During deployment, --strict-env verifies that all variables detected by the audit scanner exist in the environment or local .env files before proceeding.

Examples#

$ atlas audit ./apps/web
PRE-FLIGHT SECRET AUDIT
  Target:      D:/projects/monorepo/apps/web

  KEY                   SOURCE           STATUS
  ───────────────────   ──────────────   ──────────────
  DATABASE_URL          .env.example     ✓ found local
  NEXT_PUBLIC_API_URL   src/lib/api.ts   ✓ found local
  STRIPE_SECRET_KEY     .env.example     ✗ missing

⚠ Found 2 configured, 1 missing environment variable(s).

`atlas debug run-command`#

Run an arbitrary shell command in a workspace and show output. Useful for debugging build detection.

atlas debug run-command <path> -- <command> [args...]

$ atlas debug run-command ./my-app -- npm run build
> my-app@1.0.0 build
> vite build
...

Setting Up Credentials#

LLM Providers (Environment Variables)#

Atlas automatically loads .env from the project's root via godotenv. Set the API key for your chosen provider before running:

.env

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# Mistral
MISTRAL_API_KEY=...

# OpenAI
OPENAI_API_KEY=sk-...

# Groq
GROQ_API_KEY=gsk_...

# Gemini
GEMINI_API_KEY=...

# xAI (Grok)
XAI_API_KEY=...

Vercel Deployment Configurations#

Step 1

Option A — Environment Variable (CI/CD) Set your Vercel token securely in your environment variables.

VERCEL_TOKEN=<your-vercel-token>

Step 2

Option B — CLI Interactive Setup Securely store your token in your local OS keychain using Atlas.

atlas providers set vercel
# Prompts for masked input

Step 3

Option C — CLI Login Callback If no token is found, Atlas will prompt to launch the Vercel interactive login.

atlas <path> --provider vercel
# Atlas will prompt to run `vercel login` if needed

Config File (`.atlas/config.json`)#

You can define project-level defaults in a .atlas/config.json file.

.atlas/config.json

{
  "llm_provider": "mistral",
  "default_model": "mistral-large-latest",
  "approval": "manual"
}

Supported llm_provider values: anthropic, openai, gemini, mistral, groq, grok, local.

For local models via Ollama:

.atlas/config.json

{
  "llm_provider": "local",
  "default_model": "llama3",
  "local_llm_base_url": "http://localhost:11434/v1"
}

PreviousGetting started NextReact guide

Atlas Commands

Atlas CLI Commands#

atlas#

Flags#

Examples#

atlas providers#

Flags#

Subcommands#

atlas models#

Subcommands#

atlas testllm#

atlas status#

Flags#

atlas doctor#

Flags#

Diagnostic Categories#

atlas audit#

Flags#

Examples#

atlas debug run-command#

Setting Up Credentials#

LLM Providers (Environment Variables)#

Vercel Deployment Configurations#

Config File (.atlas/config.json)#

`atlas`#

`atlas providers`#

`atlas models`#

`atlas testllm`#

`atlas status`#

`atlas doctor`#

`atlas audit`#

`atlas debug run-command`#

Config File (`.atlas/config.json`)#