CLI Reference

The Atlas CLI (atlas) profiles databases, generates semantic layers, validates configuration, and queries data from the terminal.

# Run via bun workspace
bun run atlas -- <command> [options]

# Or directly (if installed globally)
atlas <command> [options]

init

Profile a database and generate semantic layer YAML files.

bun run atlas -- init [options]

Examples:

# Profile all tables in the default schema
bun run atlas -- init

# Profile specific tables only
bun run atlas -- init --tables users,orders,products

# Profile a non-public schema
bun run atlas -- init --schema analytics

# Profile with LLM enrichment
bun run atlas -- init --enrich

# Load the cybersec demo dataset (62 tables, ~500K rows)
bun run atlas -- init --demo cybersec

# Profile a named connection from atlas.config.ts
bun run atlas -- init --connection warehouse

# Profile CSV files directly (no database needed)
bun run atlas -- init --csv sales.csv,products.csv

# Per-source layout (writes to semantic/warehouse/)
bun run atlas -- init --source warehouse

# Org-scoped: writes to semantic/.orgs/org-123/ and imports to DB
bun run atlas -- init --org org-123

# Org-scoped, disk only (skip DB import)
bun run atlas -- init --org org-123 --no-import

--demo without an argument loads the simple dataset (3 tables, ~330 rows). --demo cybersec loads the cybersec dataset (62 tables, ~500K rows). --demo ecommerce loads the e-commerce dataset (52 tables, ~480K rows).

--connection and --source cannot be used together. Here's how they differ:

• No flag — Profiles the default datasource (ATLAS_DATASOURCE_URL) and writes output to semantic/entities/.
• --source <name> — Writes output to semantic/<name>/entities/ (for multi-source layouts where you organize by source). Does not change which datasource is profiled.
• --connection <name> — Profiles a named datasource defined in atlas.config.ts (e.g. datasources.warehouse) and automatically writes output to the matching semantic/<name>/ subdirectory.

If more than 20% of tables fail to profile, init exits with an error — this usually indicates a systemic issue like wrong credentials or missing permissions. Use --force to override this threshold.

In TTY mode (interactive terminal), init presents a table picker. Pass --tables to skip the picker for scripted/CI usage.

What it generates:

• semantic/entities/*.yml — One file per table/view with columns, types, sample values, joins, measures, virtual dimensions, and query patterns
• semantic/metrics/*.yml — Atomic and breakdown metrics per table
• semantic/glossary.yml — Ambiguous terms, FK relationships, enum definitions
• semantic/catalog.yml — Table catalog with use_for and common_questions

diff

Compare the database schema against the existing semantic layer. Exits with code 1 if drift is detected.

bun run atlas -- diff [options]

Examples:

# Check all tables for schema drift
bun run atlas -- diff

# Check specific tables only
bun run atlas -- diff --tables users,orders

# CI usage: fail the build if schema drifted
bun run atlas -- diff || echo "Schema drift detected!"

query

Ask a natural language question and get an answer. Calls POST /api/v1/query on a running Atlas API server — only bun run dev:api is needed (the full Next.js stack is not required).

bun run atlas -- query "your question" [options]

Environment:

Examples:

# Default: formatted table output with narrative explanation
bun run atlas -- query "How many users signed up last month?"

# JSON: structured response for piping to jq or other scripts
bun run atlas -- query "top 10 customers by revenue" --json

# CSV: headers + rows only, redirect to file for reports
bun run atlas -- query "monthly revenue by product" --csv > report.csv

# Quiet: raw data with no narrative, SQL, or stats
bun run atlas -- query "active users today" --quiet

# Target a named datasource from atlas.config.ts
bun run atlas -- query "warehouse inventory" --connection warehouse

doctor

Alias for validate with relaxed exit codes. Runs the same config, semantic layer, and connectivity checks, but Sandbox and Internal DB failures do not cause exit 1 — they still appear in the output but are excluded from the exit code calculation.

bun run atlas -- doctor

No flags. Use doctor in environments where Sandbox or Internal DB are intentionally absent but other services (datasource, LLM provider) are available. Use validate --offline for fast CI checks that skip all connectivity. Use validate when you want strict exit codes for all failures.

Exit codes: 0 = all pass (Sandbox/Internal DB failures excluded), 1 = any non-excluded failure, 2 = warnings only.

Example output:

  Config
    ✓ atlas.config.ts  Valid (defineConfig)

  Semantic Layer
    ✓ semantic/entities/     5 entities parsed
    ✓ semantic/glossary.yml  Valid (12 terms)
    ✓ semantic/catalog.yml   Valid
    ✓ semantic/metrics/      2 metrics parsed

  Connectivity
    ✓ ATLAS_DATASOURCE_URL  Set (postgresql://…@localhost:5432/atlas)
    ✓ Database connectivity  Connected (PostgreSQL 16.1)
    ✓ LLM provider           anthropic (ANTHROPIC_API_KEY set)
    ✓ Sandbox                nsjail available
    ✓ Internal DB            Connected

validate

Validate config, semantic layer, and connectivity. Checks that configuration is correct, semantic layer YAML files are valid, and all services are reachable.

bun run atlas -- validate [options]

Checks:

• Config — atlas.config.ts presence and structure
• Semantic layer — YAML syntax, required fields, column types, join references, metric SQL, glossary entries, cross-references
• Connectivity (unless --offline) — datasource, database, LLM provider, sandbox, internal DB

Exit codes: 0 = all pass, 1 = any failure, 2 = warnings only.

Useful in CI to catch errors before deployment. Use --offline for fast, local-only validation.

mcp

Start an MCP (Model Context Protocol) server for use with Claude Desktop, Cursor, and other MCP-compatible clients.

bun run atlas -- mcp [options]

When to use each transport:

• stdio (default) — For local MCP clients that launch the server as a subprocess (Claude Desktop, Cursor, Windsurf). The client manages the process lifecycle. This is the most common setup.
• sse — For remote or containerized MCP servers where the client connects over HTTP. Use this when the MCP server runs in a Docker container, on a remote host, or when multiple clients need to share one server instance. Clients connect via http://host:port/mcp.

Examples:

# Start MCP server on stdio (default, for Claude Desktop)
bun run atlas -- mcp

# Start with SSE transport on a custom port
bun run atlas -- mcp --transport sse --port 9090

Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "atlas": {
      "command": "bun",
      "args": ["run", "atlas", "--", "mcp"],
      "env": {
        "ATLAS_DATASOURCE_URL": "postgresql://user:pass@host:5432/db",
        "ATLAS_PROVIDER": "anthropic",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

eval

Run the evaluation pipeline against demo schemas. Used to measure text-to-SQL accuracy.

Test cases are YAML files in eval/cases/, organized by dataset (simple/, cybersec/, ecommerce/). Each case specifies id, question, schema, difficulty, category, gold_sql, and optionally expected_rows and tags. Results are written to JSONL files and can be compared against baselines for regression detection.

bun run atlas -- eval [options]

smoke

Run end-to-end smoke tests against a running Atlas deployment.

bun run atlas -- smoke [options]

Environment: Flags can also be set via environment variables. --target falls back to ATLAS_API_URL, and --api-key falls back to ATLAS_API_KEY. Explicit flags take precedence.

plugin

Manage Atlas plugins.

plugin list

List installed plugins from atlas.config.ts.

bun run atlas -- plugin list

plugin create

Scaffold a new plugin.

bun run atlas -- plugin create <name> --type <type>

plugin add

Install a plugin package.

bun run atlas -- plugin add <package-name>

migrate

Generate or apply plugin schema migrations.

bun run atlas -- migrate [options]

index

Rebuild the semantic index from current YAML files, or print index statistics. The semantic index is a pre-computed text summary of the semantic layer that the agent receives as context — it condenses all entities, columns, metrics, and glossary terms so the agent can find relevant tables without reading every YAML file via the explore tool.

bun run atlas -- index [options]

Examples:

# Rebuild the semantic index
bun run atlas -- index

# Check index stats without rebuilding
bun run atlas -- index --stats

--stats prints a one-line summary: entity count, dimensions, measures, metrics, glossary terms, and total keywords. Use this to verify the index covers your semantic layer after adding or removing entity files.

A full rebuild loads all YAML files under semantic/ (including per-source subdirectories) and validates they parse correctly. The command prints the number of indexed entities, dimensions, measures, keyword count, and elapsed time on success.

import

Import semantic layer YAML files from disk into the internal database for the active organization. Calls POST /api/v1/admin/semantic/org/import on a running Atlas API server.

This is used in multi-tenant (org-scoped) deployments where the semantic layer is stored in the internal database rather than read from disk at runtime. After running atlas init --org <orgId> to generate YAML files on disk, use atlas import to sync them into the database.

bun run atlas -- import [options]

Environment:

Requires a running Atlas API server (bun run dev:api or production deployment).

Examples:

# Import all semantic layer files for the active org
bun run atlas -- import

# Import and associate entities with a specific datasource
bun run atlas -- import --connection warehouse

Output:

The command reports how many entities were imported, how many were skipped (already up to date), the total count, and any errors encountered during import.

learn

Analyze the audit log and propose semantic layer YAML improvements. This is Atlas's offline learning loop — it examines real query patterns and suggests additions to your entity files, joins, and glossary.

bun run atlas -- learn [options]

Requires DATABASE_URL to be set (the audit log lives in the internal database).

Proposals include:

• Query patterns — frequently-used SQL not yet documented in entity YAML
• Join discoveries — table pairs queried together but with no join defined
• Glossary terms — column aliases used often enough to warrant a glossary entry

# Preview proposals (dry run, the default)
atlas learn

# Apply changes to YAML files
atlas learn --apply

# Only analyze recent queries
atlas learn --since 2026-03-01 --limit 500

# Generate query suggestions from audit log
atlas learn --suggestions

benchmark

Run the BIRD benchmark for text-to-SQL accuracy evaluation. This is a developer tool for measuring Atlas's query generation quality.

BIRD is an external academic benchmark dataset (~1500 questions across 11 SQLite databases) and is not included in the Atlas repository. You must download the BIRD dev set separately from the BIRD website and point --bird-path to the extracted directory.

bun run atlas -- benchmark [options]

export

Export workspace data to a portable migration bundle (JSON). Reads from the internal database. Used as the first step in a self-hosted → SaaS migration workflow. See Migration guide for the full workflow.

bun run atlas -- export [options]

Requires DATABASE_URL to be set (reads from the internal database).

Examples:

# Export all workspace data to a timestamped file
bun run atlas -- export

# Export to a specific file
bun run atlas -- export --output backup.json

# Export a specific organization's data
bun run atlas -- export --org org_abc123

migrate-import

Import an export bundle into a hosted Atlas instance. Used for self-hosted → SaaS migration. Calls the target instance's internal migration API endpoint.

bun run atlas -- migrate-import --bundle <path> [options]

Examples:

# Import into the hosted SaaS (default target)
bun run atlas -- migrate-import --bundle atlas-export-2026-04-02.json

# Import into a self-hosted instance
bun run atlas -- migrate-import --bundle backup.json --target https://atlas.internal.company.com

# Use env var for the API key
ATLAS_API_KEY=sk-... bun run atlas -- migrate-import --bundle backup.json

completions

Output a shell completion script for bash, zsh, or fish. Completions cover all commands and their flags.

bun run atlas -- completions <bash|zsh|fish>

No flags. The only argument is the target shell. If the shell argument is missing or unsupported, the command prints usage instructions and exits with code 1.

Installation (assumes atlas is installed globally or aliased — substitute bun run atlas -- if running from the monorepo):

Examples:

# Generate and activate bash completions for the current session
eval "$(bun run atlas -- completions bash)"

# Persist zsh completions across sessions
echo 'eval "$(atlas completions zsh)"' >> ~/.zshrc

# Install fish completions (saved to file, auto-loaded by fish)
bun run atlas -- completions fish > ~/.config/fish/completions/atlas.fish

See Also

• Schema Evolution — Detecting database drift with atlas diff and updating entity YAMLs
• MCP Server — Using atlas mcp with Claude Desktop and Cursor
• Environment Variables — Variables that affect CLI behavior (ATLAS_DATASOURCE_URL, ATLAS_SCHEMA, etc.)
• Configuration — Declarative config file that the CLI reads and validates
• Troubleshooting — Diagnostic steps when CLI commands fail