cassady/docs/commands.md

Commands

Cassady installs two equivalent binaries: cass and cassady. This page uses cass, but the same options and subcommands apply to cassady.

Top-level forms

cass [OPTIONS]
cassady [OPTIONS]
cass check [OPTIONS]
cass setup [OPTIONS]
cass update [OPTIONS]
cass --resume [CHAT_ID]

Run cass --help, cass check --help, cass setup --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 OpenAI-compatible base URL 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 API key availability.

Missing API keys for inactive providers are warnings. A missing active API key is an error and cass check exits with a non-zero status.

cass setup

Runs the interactive setup wizard in a terminal. It configures OpenAI-compatible providers, API key environment-variable references, and first models. It updates config.json, providers.json, and models.json while preserving unrelated entries where possible.

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 both cass and cassady, 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.

• /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, 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.
• Ctrl-C: request cancellation while busy; press twice within 1.5 seconds to exit.

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.