cassady/docs/commands.md

Commands

Cassady installs two equivalent CLI binaries: cass and cassady. This page uses cass, but the same options and subcommands apply to cassady. macOS/Linux release archives also include a cassady-desktop companion binary launched by cass desktop.

Top-level forms

cass [OPTIONS]
cassady [OPTIONS]
cass check [OPTIONS]
cass login [OPTIONS]
cass logout [OPTIONS]
cass setup [OPTIONS]
cass desktop [OPTIONS]
cass update [OPTIONS]
cass --resume [CHAT_ID]

Run cass --help, cass check --help, cass login --help, cass logout --help, cass setup --help, cass desktop --help, or cass update --help for the help generated by the current binary.

Startup behavior

• cass starts a new interactive chat in the current directory.
• cass --cwd PATH starts from PATH instead.
• cass --resume CHAT_ID loads a saved chat.
• cass --resume lists chats for the current directory.
• If setup is incomplete, cass offers to run the interactive setup wizard before starting a chat.

On exit, Cassady prints a command like:

Resume this chat with: cass --resume <id>

Global options

• --resume [CHAT_ID]: resume a chat, or list chats for the current cwd when no id is provided.
• --model MODEL: use MODEL for this session.
• --base-url URL: override the active provider's base URL or endpoint for this session.
• --api-key-env ENV: read the API key from environment variable ENV for this session.
• --cwd PATH: use PATH as the launch cwd and workspace root.
• --readonly: force read-only mode.
• --workspace-edit: force workspace-edit mode.
• --full-access: force full-access mode.
• --help: show help.
• --version: show version.

The three access-mode flags conflict with one another.

Subcommands

cass check

Validates Cassady configuration under ~/.cass:

• JSON syntax and schema.
• duplicate provider/model ids.
• model/provider references.
• active provider and model resolution.
• active authentication availability.

Missing API keys for inactive OpenAI-compatible providers are warnings. A missing active API key is an error. For ChatGPT Codex, missing or expired local Codex auth is an error when it is active. cass check exits with a non-zero status when errors are present.

cass login

Runs the provider login/configuration wizard. This is the same provider setup flow used by cass setup, framed for adding or updating saved provider access. It can configure multiple providers, discover or manually enter models, update active defaults, and validate the saved files.

cass login edits Cassady files under ~/.cass; it does not create provider accounts. For ChatGPT Codex, sign in with codex login or the Codex app first; Cassady then uses local Codex auth instead of storing an API key.

cass logout

Opens an interactive menu for removing saved providers from Cassady config. Removing a provider also removes its associated models.json entries. If the active provider is removed, Cassady chooses a remaining provider/model when possible. If no providers remain, active defaults are cleared and the next chat startup will offer setup/login again.

cass logout does not delete environment variables, API keys stored elsewhere, or external provider accounts.

cass setup

Runs the interactive setup wizard in a terminal. It configures providers, authentication sources, and first models. OpenAI-compatible providers use API key environment-variable references; ChatGPT Codex uses local Codex auth. It updates config.json, providers.json, and models.json while preserving unrelated entries where possible.

cass desktop

Launches the Cassady desktop app and immediately detaches it from the terminal, so the app window can keep running after you close the terminal. The desktop binary must be installed as cassady-desktop next to cass or somewhere on PATH. You can also set CASSADY_DESKTOP_BIN=/path/to/cassady-desktop.

Useful option:

• --foreground: keep the desktop process attached to the terminal for debugging.

Use cass --cwd PATH desktop to choose the launch cwd/workspace root for the desktop app.

cass update

Checks official GitHub releases for Cassady, including Cassady prereleases, and updates the current install directory. The updater runs before provider/model config is loaded, so it can be used even if ~/.cass is missing or invalid.

By default, Cassady selects the matching prebuilt archive for the current platform, downloads the archive and .sha256 file, verifies SHA-256, stages cass and cassady, stages cassady-desktop when the archive contains it, and replaces same-directory binaries with rollback backups. If no prebuilt archive is available, it can build from the selected release source when you choose source mode.

Useful options:

• --check: check the selected release without installing.
• --dry-run: show the selected release, mode, asset, and install plan without downloading or installing.
• --yes / -y: accept default prompts for non-interactive use.
• --prebuilt: require a matching prebuilt archive.
• --source: build from release source even when a prebuilt archive exists.
• --to TAG: use a specific release tag such as v0.2.7.

Examples:

cass update --check
cass update --dry-run
cass update
cass update --source

The updater does not invoke sudo or administrator prompts. If the install directory is not writable, rerun the update from an install location you own or update through the same package manager or manual process you originally used.

In-chat commands

Type / to open command autocomplete.

• /branch or /restore: open the branch/restore menu for the current conversation family.
• /fast, /fast on, /fast off, /fast status: toggle or inspect a persisted fast-mode preference. Fast mode is active only when the current provider/model supports it; ChatGPT Codex models, including gpt-5.5, are treated as fast-capable.
• /login: configure or update provider login settings, then reload active provider/model config.
• /logout: remove saved providers and their associated models, then reload active provider/model config when any remain.
• /model <model>: switch the model for future turns. Autocomplete lists models from ~/.cass/models.json.
• /new: create a new chat for the current directory.
• /resume <chat>: resume a saved chat from the current directory. Autocomplete lists matching chats.
• /status: show chat id, state, model, fast-mode state, access mode, cwd, record count, and current status.

Local commands can be used only when the agent is idle.

Keys

• Enter: accept an autocomplete item when a menu is open; otherwise send the current message.
• Ctrl-J or Ctrl-Enter: insert a newline.
• Up/Down: move through autocomplete items when a menu is open; otherwise scroll the transcript.
• Mouse wheel: scroll transcript.
• PageUp/PageDown: scroll transcript by larger steps.
• Shift-Tab: cycle access mode while idle: read-only → workspace-edit → full-access.
• Tab: cycle reasoning effort while idle. Models that require reasoning skip off; models without reasoning metadata start at off.
• Ctrl-O: toggle compact/full tool output display.
• Ctrl-Shift-R or Ctrl-R: toggle reasoning display.
• y: approve a pending tool approval prompt.
• n or Esc: deny a pending tool approval prompt.
• Esc: request cancellation while a turn is running.
• Esc twice while idle: open the branch/restore menu without discarding draft input.
• Ctrl-C: request cancellation while busy; press twice within 1.5 seconds to exit.

Branch/restore notes

The branch/restore menu lists related conversations plus checkpoints for user messages, assistant messages, tool-call requests, and tool results. Selecting a checkpoint creates a new branch JSONL conversation and leaves the source conversation unchanged. Conversation-only branching leaves files untouched; branch-plus-file restore applies Cassady's tracked write/edit snapshots and skips unsafe hash conflicts.

Output notes

Tool calls are shown compactly by default. Press Ctrl-O to expand full tool output. Provider-streamed reasoning is hidden by default unless show_reasoning is enabled in config or toggled at runtime.