143 lines
6.9 KiB
Markdown
143 lines
6.9 KiB
Markdown
# 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
|
|
|
|
```sh
|
|
cass [OPTIONS]
|
|
cassady [OPTIONS]
|
|
cass check [OPTIONS]
|
|
cass login [OPTIONS]
|
|
cass logout [OPTIONS]
|
|
cass setup [OPTIONS]
|
|
cass update [OPTIONS]
|
|
cass --resume [CHAT_ID]
|
|
```
|
|
|
|
Run `cass --help`, `cass check --help`, `cass login --help`, `cass logout --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:
|
|
|
|
```text
|
|
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 login`
|
|
|
|
Runs the provider login/configuration wizard. This is the same provider setup flow used by `cass setup`, framed for adding or updating saved OpenAI-compatible 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 sign in through a browser or create provider accounts.
|
|
|
|
### `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 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:
|
|
|
|
```sh
|
|
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.
|
|
- `/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, 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.
|