# Atlas CLI reference

> Every command, flag, type, and default in the Atlas CLI.

This file is generated from the CLI's own argument definitions, not written by hand. If a flag is not listed here, it does not exist. Do not infer flags from other tools.

Generated from the Atlas source tree at version 1.17.11. That is the tree this file was built from, which is not necessarily the version you have installed: the stable channel can be ahead. For the version actually shipping, read `https://admin.runatlas.sh/api/releases/installer-manifest?channel=stable`, or run `atlas --version`.

Commands and flags change far more slowly than patch versions, so this reference stays accurate across patch releases. Where they disagree, the binary wins.

## Install

```sh
curl -fsSL https://runatlas.sh/install | sh
```

## Commands

| Command | Description |
| --- | --- |
| `atlas acp` | start ACP (Agent Client Protocol) server |
| `atlas agent` | manage agents |
| `atlas` | start Atlas tui |
| `atlas attach` | attach to a running Atlas server |
| `atlas console` |  |
| `atlas db` | database tools |
| `atlas debug` | debugging and troubleshooting tools |
| `atlas device` | manage local device identity |
| `atlas export` | export session data as JSON |
| `atlas generate` |  |
| `atlas github` | manage GitHub agent |
| `atlas import` | import session data from JSON file or URL |
| `atlas login` | create or sign in to your free Atlas account |
| `atlas logout` | sign out of Atlas |
| `atlas mcp` | manage MCP (Model Context Protocol) servers |
| `atlas models` | list all available models |
| `atlas plugin` | install plugin and update config |
| `atlas pr` | fetch and checkout a GitHub PR branch, then run Atlas |
| `atlas providers` | manage AI providers and credentials |
| `atlas run` | run Atlas with a message |
| `atlas serve` | starts a headless Atlas server |
| `atlas session` | manage sessions |
| `atlas stats` | show token usage and cost statistics |
| `atlas uninstall` | uninstall Atlas and remove all related files |
| `atlas upgrade` | upgrade Atlas to the latest or a specific version |
| `atlas web` | start Atlas server and open web interface |

### Aliases

| Alias | Resolves to |
| --- | --- |
| `atlas signin` | Alias for `atlas login` |
| `atlas signup` | Alias for `atlas login` |
| `atlas auth` | Alias for `atlas providers` |
| `atlas update` | Alias for `atlas upgrade` |
| `atlas plug` | Alias for `atlas plugin` |

## Reference

### `atlas acp`

start ACP (Agent Client Protocol) server

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--port` | number | `0` | port to listen on |
| `--hostname` | string | `"127.0.0.1"` | hostname to listen on |
| `--mdns` | boolean | `false` | enable mDNS service discovery (defaults hostname to 0.0.0.0) |
| `--mdns-domain` | string | `"atlas.local"` | custom domain name for mDNS service (default: atlas.local) |
| `--cors` | string[] | `[]` | additional domains to allow for CORS |
| `--cwd` | string | `"C:\\Users\\Parker Gawne\\Desktop\\Syntora\\atlas\\Atlas-Backend\\atlas"` | working directory |

### `atlas agent`

manage agents

#### `atlas agent create`

create a new agent

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--path` | string |  | directory path to generate the agent file |
| `--description` | string |  | what the agent should do |
| `--mode` | `all` \| `primary` \| `subagent` |  | agent mode |
| `--tools, --permissions` | string |  | comma-separated list of permissions to allow (default: all). Available: "bash, read, edit, glob, grep, webfetch, task, todowrite, websearch, lsp, skill" |
| `-m, --model` | string |  | model to use in the format of provider/model |

#### `atlas agent list`

list all available agents

### `atlas [project]`

start Atlas tui

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `project` | string |  | path to start Atlas in |

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--port` | number | `0` | port to listen on |
| `--hostname` | string | `"127.0.0.1"` | hostname to listen on |
| `--mdns` | boolean | `false` | enable mDNS service discovery (defaults hostname to 0.0.0.0) |
| `--mdns-domain` | string | `"atlas.local"` | custom domain name for mDNS service (default: atlas.local) |
| `--cors` | string[] | `[]` | additional domains to allow for CORS |
| `-m, --model` | string |  | model to use in the format of provider/model |
| `-c, --continue` | boolean |  | continue the last session |
| `-s, --session` | string |  | session id to continue |
| `--fork` | boolean |  | fork the session when continuing (use with --continue or --session) |
| `--prompt` | string |  | prompt to use |
| `--agent` | string |  | agent to use |
| `--renderer` | `opentui` \| `atlas-engine` |  | renderer adapter to use |

### `atlas attach <url>`

attach to a running Atlas server

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `url` | string |  | http://localhost:4096 |

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--dir` | string |  | directory to run in |
| `-c, --continue` | boolean |  | continue the last session |
| `-s, --session` | string |  | session id to continue |
| `--fork` | boolean |  | fork the session when continuing (use with --continue or --session) |
| `-p, --password` | string |  | basic auth password (defaults to ATLAS_SERVER_PASSWORD) |
| `-u, --username` | string |  | basic auth username (defaults to ATLAS_SERVER_USERNAME or 'atlas') |

### `atlas console`

#### `atlas console login [url]`

log in to console

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `url` | string |  | server URL |

#### `atlas console logout [email]`

log out from console

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `email` | string |  | account email to log out from |

#### `atlas console switch`

switch active org

#### `atlas console orgs`

list orgs

#### `atlas console open`

open active console account

### `atlas db`

database tools

#### `atlas db $0 [query]`

open an interactive sqlite3 shell or run a query

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | string |  | SQL query to execute |

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--format` | `json` \| `tsv` | `"tsv"` | Output format |

#### `atlas db path`

print the database path

### `atlas debug`

debugging and troubleshooting tools

#### `atlas debug config`

show resolved configuration

#### `atlas debug lsp`

LSP debugging utilities

##### `atlas lsp diagnostics <file>`

get diagnostics for a file

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `file` | string |  |  |

##### `atlas lsp symbols <query>`

search workspace symbols

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | string |  |  |

##### `atlas lsp document-symbols <uri>`

get symbols from a document

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `uri` | string |  |  |

#### `atlas debug rg`

ripgrep debugging utilities

##### `atlas rg files`

list files using ripgrep

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--query` | string |  | Filter files by query |
| `--glob` | string |  | Glob pattern to match files |
| `--limit` | number |  | Limit number of results |

##### `atlas rg search <pattern>`

search file contents using ripgrep

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `pattern` | string |  | Search pattern |

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--glob` | array |  | File glob patterns |
| `--limit` | number |  | Limit number of results |

#### `atlas debug file`

file system debugging utilities

##### `atlas file read <path>`

read file contents as JSON

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | string |  | File path to read |

##### `atlas file list <path>`

list files in a directory

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | string |  | File path to list |

##### `atlas file search <query>`

search files by query

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | string |  | Search query |

#### `atlas debug scrap`

list all known projects

#### `atlas debug skill`

list all available skills

#### `atlas debug snapshot`

snapshot debugging utilities

##### `atlas snapshot track`

track current snapshot state

##### `atlas snapshot patch <hash>`

show patch for a snapshot hash

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `hash` | string |  | hash |

##### `atlas snapshot diff <hash>`

show diff for a snapshot hash

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `hash` | string |  | hash |

#### `atlas debug startup`

print startup timing

#### `atlas debug agent <name>`

show agent configuration details

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | string |  | Agent name |

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--tool` | string |  | Tool id to execute |
| `--params` | string |  | Tool params as JSON or a JS object literal |

#### `atlas debug v2`

debug v2 catalog and built-in plugins

#### `atlas debug project-intelligence`

show deterministic project intelligence brief

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--json` | boolean | `false` | print the raw brief as JSON |

#### `atlas debug info`

show debug information

#### `atlas debug paths`

show global paths (data, config, cache, state)

#### `atlas debug wait`

wait indefinitely (for debugging)

### `atlas device`

manage local device identity

#### `atlas device current`

show the current local device

#### `atlas device list`

list registered devices

### `atlas export [sessionID]`

export session data as JSON

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `sessionID` | string |  | session id to export |

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--sanitize` | boolean |  | redact sensitive transcript and file data |

### `atlas generate`

### `atlas github`

manage GitHub agent

#### `atlas github install`

install the GitHub agent

#### `atlas github run`

run the GitHub agent

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--event` | string |  | GitHub mock event to run the agent for |
| `--token` | string |  | GitHub personal access token (github_pat_********) |

### `atlas import <file>`

import session data from JSON file or URL

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `file` | string |  | path to JSON file or share URL |

### `atlas login`

create or sign in to your free Atlas account

### `atlas logout`

sign out of Atlas

### `atlas mcp`

manage MCP (Model Context Protocol) servers

#### `atlas mcp add [name]`

add an MCP server

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | string |  | name of the MCP server |

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--url` | string |  | URL for a remote MCP server |
| `--env` | string[] |  | environment variable for a local MCP server (KEY=VALUE) |
| `--header` | string[] |  | HTTP header for a remote MCP server (KEY=VALUE) |

#### `atlas mcp list`

list MCP servers and their status

#### `atlas mcp auth [name]`

authenticate with an OAuth-enabled MCP server

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | string |  | name of the MCP server |

##### `atlas auth list`

list OAuth-capable MCP servers and their auth status

#### `atlas mcp logout [name]`

remove OAuth credentials for an MCP server

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | string |  | name of the MCP server |

#### `atlas mcp debug <name>`

debug OAuth connection for an MCP server

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | string |  | name of the MCP server |

### `atlas models [provider]`

list all available models

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `provider` | string |  | provider ID to filter models by |

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--verbose` | boolean |  | use more verbose model output (includes metadata like costs) |
| `--refresh` | boolean |  | refresh the models cache from models.dev |
| `--local` | boolean |  | detect a local Ollama or LM Studio server and register its models as a provider |

### `atlas plugin <module>`

install plugin and update config

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `module` | string |  | npm module name |

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `-g, --global` | boolean | `false` | install in global config |
| `-f, --force` | boolean | `false` | replace existing plugin version |

### `atlas pr <number>`

fetch and checkout a GitHub PR branch, then run Atlas

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `number` | number |  | PR number to checkout |

### `atlas providers`

manage AI providers and credentials

#### `atlas providers list`

list providers and credentials

#### `atlas providers login [url]`

log in to a provider

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `url` | string |  | atlas auth provider |

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `-p, --provider` | string |  | provider id or name to log in to (skips provider selection) |
| `-m, --method` | string |  | login method label (skips method selection) |

#### `atlas providers logout [provider]`

log out from a configured provider

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `provider` | string |  | provider id or name to log out from |

### `atlas run [message..]`

run Atlas with a message

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `message` | string[] | `[]` | message to send |

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--command` | string |  | the command to run, use message for args |
| `-c, --continue` | boolean |  | continue the last session |
| `-s, --session` | string |  | session id to continue |
| `--fork` | boolean |  | fork the session before continuing (requires --continue or --session) |
| `--share` | boolean |  | share the session |
| `-m, --model` | string |  | model to use in the format of provider/model |
| `--agent` | string |  | agent to use |
| `--format` | `default` \| `json` | `"default"` | format: default (formatted) or json (raw JSON events) |
| `-f, --file` | string[] |  | file(s) to attach to message |
| `--title` | string |  | title for the session (uses truncated prompt if no value provided) |
| `--attach` | string |  | attach to a running Atlas server (e.g., http://localhost:4096) |
| `-p, --password` | string |  | basic auth password (defaults to ATLAS_SERVER_PASSWORD) |
| `-u, --username` | string |  | basic auth username (defaults to ATLAS_SERVER_USERNAME or 'atlas') |
| `--dir` | string |  | directory to run in, path on remote server if attaching |
| `--port` | number |  | port for the local server (defaults to random port if no value provided) |
| `--variant` | string |  | model variant (provider-specific reasoning effort, e.g., high, max, minimal) |
| `--speed` | `auto` \| `fast` \| `balanced` \| `thorough` | `"auto"` | answer speed preset; maps to the nearest supported reasoning variant |
| `--fast` | boolean | `false` | shortcut for --speed fast |
| `--thinking` | boolean |  | show thinking blocks |
| `--replay` | boolean | `true` | replay interactive session history on resume and after resize (use --no-replay to disable) |
| `--replay-limit` | number |  | cap visible interactive replay to the newest N messages |
| `-i, --interactive` | boolean | `false` | run in direct interactive split-footer mode |
| `--dangerously-skip-permissions` | boolean | `false` | auto-approve permissions that are not explicitly denied (dangerous!) |
| `--demo` | boolean | `false` | enable direct interactive demo slash commands; pass one as the message to run it immediately |

### `atlas serve`

starts a headless Atlas server

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--port` | number | `0` | port to listen on |
| `--hostname` | string | `"127.0.0.1"` | hostname to listen on |
| `--mdns` | boolean | `false` | enable mDNS service discovery (defaults hostname to 0.0.0.0) |
| `--mdns-domain` | string | `"atlas.local"` | custom domain name for mDNS service (default: atlas.local) |
| `--cors` | string[] | `[]` | additional domains to allow for CORS |

### `atlas session`

manage sessions

#### `atlas session list`

list sessions

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `-n, --max-count` | number |  | limit to N most recent sessions |
| `--format` | `table` \| `json` | `"table"` | output format |

#### `atlas session delete <sessionID>`

delete a session

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `sessionID` | string |  | session ID to delete |

### `atlas stats`

show token usage and cost statistics

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--days` | number |  | show stats for the last N days (default: all time) |
| `--tools` | number |  | number of tools to show (default: all) |
| `--models` | string |  | show model statistics (default: hidden). Pass a number to show top N, otherwise shows all |
| `--project` | string |  | filter by project (default: all projects, empty string: current project) |

### `atlas uninstall`

uninstall Atlas and remove all related files

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `-c, --keep-config` | boolean | `false` | keep configuration files |
| `-d, --keep-data` | boolean | `false` | keep session data and snapshots |
| `--dry-run` | boolean | `false` | show what would be removed without removing |
| `-f, --force` | boolean | `false` | skip confirmation prompts |

### `atlas upgrade [target]`

upgrade Atlas to the latest or a specific version

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `target` | string |  | version to upgrade to, for ex '0.1.48' or 'v0.1.48' |

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `-m, --method` | `curl` \| `npm` \| `pnpm` \| `bun` \| `brew` \| `choco` \| `scoop` |  | installation method to use |
| `-f, --force` | boolean |  | install the latest available build even when this version appears current |

### `atlas web`

start Atlas server and open web interface

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--port` | number | `0` | port to listen on |
| `--hostname` | string | `"127.0.0.1"` | hostname to listen on |
| `--mdns` | boolean | `false` | enable mDNS service discovery (defaults hostname to 0.0.0.0) |
| `--mdns-domain` | string | `"atlas.local"` | custom domain name for mDNS service (default: atlas.local) |
| `--cors` | string[] | `[]` | additional domains to allow for CORS |

---

Canonical HTML: https://runatlas.sh/docs
Source of truth: Atlas-Backend/atlas/script/generate-cli-reference.ts (run it to regenerate; never edit the JSON by hand) (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.