CLI commands

cascade [GLOBAL OPTIONS] COMMAND [COMMAND OPTIONS]

Global options

Option	Description
--version	Print the version and exit
-v, --verbose	Enable debug-level logs (stderr)
-q, --quiet	Suppress animated progress output. Useful in CI and scripted runs.
--help	Show help and exit

Commands

cascade init

Scaffold cascade.yaml and the team-memory/ directory in the current repo. Run this once per project.

cascade init [--force] [--no-seed]

Option	Description
--force	Overwrite existing files if present
--no-seed	Use bare templates instead of language-aware seeded content. By default, team-memory files are pre-seeded based on the detected language.

cascade configure

Manage credentials and defaults at ~/.config/cascade/config.yaml.

cascade configure show
cascade configure llm <provider> [OPTIONS]
cascade configure vcs <provider> [OPTIONS]
cascade configure issue <provider> [OPTIONS]

configure show prints the effective config with secrets masked. Safe to share for debugging.

configure llm <provider> sets up an LLM provider.

Option	Description
--key TEXT	API key for the provider
--model TEXT	Default model identifier
--base-url URL	Override the API base URL (for Azure, self-hosted, OpenRouter)
--set-default	Make this the default LLM provider for all commands

Supported providers: anthropic, openai, google, claude_code, ollama.

configure vcs <provider> sets up a version control provider.

Option	Description
--token TEXT	Access token
--base-url URL	Override the API base URL (for self-hosted GitHub Enterprise, GitLab)
--organization TEXT	Organization name (required for Azure DevOps)
--set-default	Make this the default VCS provider

Supported providers: github, gitlab, bitbucket, azure_devops.

configure issue <provider> sets up an issue tracker.

Option	Description
--token TEXT	Access token
--base-url URL	API base URL (required for Jira)
--user TEXT	Username or email (required for Jira)
--set-default	Make this the default issue source

Supported providers: github, jira, linear, azure_devops, gitlab.

cascade doctor

Health-check the install and report status of every component.

cascade doctor [--repo-root PATH]

Option	Description
--repo-root PATH	Repo to check. Defaults to the current directory.

Runs roughly eleven checks: Python version, optional extras (whisper, ollama-sdk, etc.), git, cascade.yaml, team memory files, language detection, LLM credentials, VCS credentials, test runner availability. Reports each as OK / WARN / FAIL with an actionable suggestion for anything not OK.

Exit codes:

• 0 if all checks passed (warnings allowed)
• 1 if one or more checks failed

cascade try

Run the built-in toy story end-to-end to verify the install works. Creates a disposable Python project in a temp directory, asks Cascade to add a hello() function and a test, runs the test, reports the result. Touches nothing in your real repos.

cascade try [--keep-workspace]

Option	Description
--keep-workspace	Do not delete the temp directory after the run. Useful for inspecting what Cascade generated.

This is the recommended thing to run right after cascade configure to verify your setup will work before you bet a real repo on it. Takes ~30 seconds; costs a few cents on a paid LLM.

Exit codes:

• 0 if the toy run passed (LLM call worked, tests passed)
• 1 if anything failed

cascade ingest

Transcribe an audio or video file into a structured transcript YAML. Requires the [ingest] extra (pip install "cascade-agent[ingest]").

cascade ingest <source> [OPTIONS]

Option	Description
-o, --output FILE	Where to write the transcript. Defaults to transcripts/{meeting_id}.yaml.
--backend NAME	auto (default), faster-whisper, local-whisper, openai-api
--model SIZE	Whisper model size (tiny, base, small, medium, large). Default base.
--language CODE	ISO 639-1 language code (en, es, fr, etc.) to force, or omit for auto-detect
--no-diarization	Skip speaker identification (faster; all turns labeled “Speaker”)
--meeting-id TEXT	Override the generated meeting ID. Default: slug of the file name.

cascade extract

Extract user stories from a transcript YAML.

cascade extract <transcript_path> [OPTIONS]

Option	Description
-o, --output FILE	Where to write the stories YAML. Default: stories/{meeting_id}.yaml.
--model TEXT	Override the configured LLM model for this call.

cascade review

Walk through extracted stories interactively (accept / edit / reject / skip / quit).

cascade review <batch_path>

Decisions are saved after every action; safe to quit any time with Ctrl-C and resume later. The web equivalent is cascade ui.

cascade prompt

Build directly from an ad-hoc prompt. The prompt is treated as an automatically-approved story.

cascade prompt "<text>" [OPTIONS]

Option	Description
--language TEXT	Override the language profile (python, typescript, etc.)
--base-branch TEXT	Branch to create the PR against. Default main.
--no-pr	Stop after the local commit; do not push or open a PR. Useful for inspecting before pushing.
--repo-root PATH	Target repo path. Default: current directory.
--max-cost USD	Maximum cumulative LLM cost before aborting. Has no effect on free providers (Claude Code, Ollama).
--model TEXT	Override the configured model for this call.

cascade ticket

Build from a tracker ticket.

cascade ticket <provider:identifier> [OPTIONS]

Option	Description
--language TEXT	Override the language profile
--base-branch TEXT	Branch to create the PR against. Default main.
--no-pr	Stop after the local commit
--repo-root PATH	Target repo path
--max-cost USD	Cost ceiling (see cascade prompt)

cascade build

Run the full pipeline (plan, code, test, PR) on every approved story in a batch.

cascade build <batch_path> [OPTIONS]

Option	Description
--story N	Build only the N-th approved story (1-indexed)
--language TEXT	Override the language profile
--base-branch TEXT	Branch to create the PR against
--no-pr	Stop after the local commit
--repo-root PATH	Target repo path
--max-cost USD	Cumulative cost ceiling across all stories in the batch

cascade status

Show the pipeline state for the current repo (transcripts and story batches counted).

cascade status

cascade ui

Launch Cascade Studio (the bundled web dashboard) and open it in your browser.

cascade ui [--host HOST] [--port PORT] [--no-browser]

Option	Description
--host TEXT	Host to bind. Default 127.0.0.1. Use 0.0.0.0 to allow connections from other machines (no auth; only do this on a trusted network).
--port INT	Port to bind. Default 8000.
--no-browser	Do not auto-open a browser window.

Requires the [studio] extra (pip install "cascade-agent[studio]").

Exit codes

Code	Meaning
0	Success
1	Generic failure (CascadeError or unrecoverable error in a stage)
2	cascade build aborted because --max-cost was exceeded
130	Interrupted (Ctrl-C)

Environment variables

Cascade reads a small number of environment variables, mostly as fallbacks if a value is not in ~/.config/cascade/config.yaml.

Variable	Used for	Notes
ANTHROPIC_API_KEY	Anthropic provider	Fallback if not configured via cascade configure llm anthropic
OPENAI_API_KEY	OpenAI provider	Fallback
GOOGLE_API_KEY or GEMINI_API_KEY	Google Gemini	Fallback (either name works)
GITHUB_TOKEN or GH_TOKEN	GitHub VCS / issues	Fallback
XDG_CONFIG_HOME	Where cascade/config.yaml lives	Default: ~/.config
CASCADE_DEBUG	Set to 1 to enable debug logging without -v	Useful in CI when you cannot pass flags

Common command patterns

From audio recording to merged PR

cascade ingest recordings/standup.mp3
cascade extract transcripts/standup.yaml
cascade review stories/standup.yaml
cascade build stories/standup.yaml

Direct prompt, then inspect locally

cascade prompt "Add /health endpoint" --no-pr
git diff HEAD~1 HEAD
# happy with it:
git push -u origin $(git branch --show-current)
gh pr create --fill
# not happy:
git checkout main && git branch -D cascade/add-health-endpoint

Build a whole sprint from Jira

for ticket in PROJ-{101..110}; do
  cascade ticket "jira:$ticket" --max-cost 1.50 || break
done

Verify install before doing anything real

cascade doctor
cascade try

Getting help

Every command supports --help:

cascade --help
cascade build --help
cascade configure llm --help

What is next

• Configuration reference for the cascade.yaml schema
• Quick examples for end-to-end command sequences
• The pipeline for what each command does internally