# SeaShell CLI reference

> Every command, flag, type, and default in the SeaShell 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 SeaShell source tree at version 1.26.0. 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.seashell.sh/api/releases/installer-manifest?channel=stable`, or run `seashell --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://seashell.sh/install | sh
```

## Commands

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

### Aliases

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

## Reference

### `seashell 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 |  | working directory |

### `seashell agent`

manage agents

#### `seashell 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 |

#### `seashell agent list`

list all available agents

### `seashell attach <url>`

attach to a running SeaShell 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 SEASHELL_SERVER_PASSWORD) |
| `-u, --username` | string |  | basic auth username (defaults to SEASHELL_SERVER_USERNAME or 'atlas') |

### `seashell console`

#### `seashell console login [url]`

log in to console

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

#### `seashell console logout [email]`

log out from console

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

#### `seashell console switch`

switch active org

#### `seashell console orgs`

list orgs

#### `seashell console open`

open active console account

### `seashell db`

database tools

#### `seashell 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 |

#### `seashell db path`

print the database path

### `seashell debug`

debugging and troubleshooting tools

#### `seashell debug config`

show resolved configuration

#### `seashell debug lsp`

LSP debugging utilities

##### `seashell lsp diagnostics <file>`

get diagnostics for a file

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

##### `seashell lsp symbols <query>`

search workspace symbols

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

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

get symbols from a document

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

#### `seashell debug rg`

ripgrep debugging utilities

##### `seashell 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 |

##### `seashell 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 |

#### `seashell debug file`

file system debugging utilities

##### `seashell file read <path>`

read file contents as JSON

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

##### `seashell file list <path>`

list files in a directory

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

##### `seashell file search <query>`

search files by query

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

#### `seashell debug scrap`

list all known projects

#### `seashell debug skill`

list all available skills

#### `seashell debug snapshot`

snapshot debugging utilities

##### `seashell snapshot track`

track current snapshot state

##### `seashell snapshot patch <hash>`

show patch for a snapshot hash

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

##### `seashell snapshot diff <hash>`

show diff for a snapshot hash

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

#### `seashell debug startup`

print startup timing

#### `seashell 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 |

#### `seashell debug v2`

debug v2 catalog and built-in plugins

#### `seashell debug project-intelligence`

show deterministic project intelligence brief

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

#### `seashell debug info`

show debug information

#### `seashell debug paths`

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

#### `seashell debug wait`

wait indefinitely (for debugging)

### `seashell device`

manage local device identity

#### `seashell device current`

show the current local device

#### `seashell device list`

list registered devices

### `seashell 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 |

### `seashell generate`

### `seashell github`

manage GitHub agent

#### `seashell github install`

install the GitHub agent

#### `seashell 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_********) |

### `seashell import <file>`

import session data from JSON file or URL

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

### `seashell login`

create or sign in to your free SeaShell account

### `seashell logout`

sign out of SeaShell

### `seashell mcp`

manage MCP (Model Context Protocol) servers

#### `seashell 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) |

#### `seashell mcp list`

list MCP servers and their status

#### `seashell mcp auth [name]`

authenticate with an OAuth-enabled MCP server

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

##### `seashell auth list`

list OAuth-capable MCP servers and their auth status

#### `seashell mcp logout [name]`

remove OAuth credentials for an MCP server

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

#### `seashell mcp debug <name>`

debug OAuth connection for an MCP server

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

### `seashell 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 |

### `seashell 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 |

### `seashell pr <number>`

fetch and checkout a GitHub PR branch, then run SeaShell

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

### `seashell providers`

manage AI providers and credentials

#### `seashell providers list`

list providers and credentials

#### `seashell 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) |

#### `seashell providers logout [provider]`

log out from a configured provider

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

### `seashell run [message..]`

run SeaShell 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 SeaShell server (e.g., http://localhost:4096) |
| `-p, --password` | string |  | basic auth password (defaults to SEASHELL_SERVER_PASSWORD) |
| `-u, --username` | string |  | basic auth username (defaults to SEASHELL_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 |
| `--dangerously-skip-permissions` | boolean | `false` | auto-approve permissions that are not explicitly denied (dangerous!) |

### `seashell [project]`

start SeaShell tui

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `project` | string |  | path to start SeaShell 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 |

### `seashell serve`

starts a headless SeaShell 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 |

### `seashell session`

manage sessions

#### `seashell session list`

list sessions

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

#### `seashell session delete <sessionID>`

delete a session

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

### `seashell 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) |

### `seashell uninstall`

uninstall SeaShell 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 |

### `seashell upgrade [target]`

upgrade SeaShell 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 |

### `seashell web`

start SeaShell 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://seashell.sh/docs
Source of truth: SeaShell-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: SeaShell is proprietary with a free core. It is not open source and there is no public source repository.