CLI reference

Auto-generated from typescript/cast-cli/src/commands/ on every build. If a command is missing or its description looks wrong, that file is the source of truth.

Contents

Core commands

cast clone

Clone an agent from a Git repository

cast clone <url> [name]

Arguments

NameDescriptionRequired
url Git repository URL yes
name Local agent name (optional, defaults to repo name) no

Examples

cast clone https://github.com/user/my-agent
cast clone git@github.com:user/my-agent.git
cast clone https://github.com/user/my-agent cool-agent

Source: typescript/cast-cli/src/commands/clone.ts

cast connect

Connect to deployed agent

cast connect <agent> [flags]

Arguments

NameDescriptionRequired
agent Agent name or deployment SHA yes

Flags

FlagDescriptionTypeDefault
--proxy Use sprite proxy for sprites deployments boolean false
--sha Treat input as deployment SHA (auto-detected) boolean false

Examples

cast connect email-agent
cast connect abc123  # Connect by deployment SHA

Source: typescript/cast-cli/src/commands/connect.ts

cast delete

Delete agent

cast delete <agent> [flags]

Arguments

NameDescriptionRequired
agent Agent name yes

Flags

FlagDescriptionTypeDefault
--force Force deletion without confirmation boolean false

Source: typescript/cast-cli/src/commands/delete.ts

cast deploy

Deploy agent to hosting provider

cast deploy <agent> [flags]

Arguments

NameDescriptionRequired
agent Agent name yes

Flags

FlagDescriptionTypeDefault
-f, --force Skip all interactive prompts (auto-commit uncommitted changes before deploying) boolean false
--provider <provider> Deployment provider string —
--port <port> Port for local deployment integer 8080
--version <version> Release version to deploy (defaults to latest/current state) string latest
--size <size> DigitalOcean MicroVM size as cpu:memory-mib. One of 1:2048, 2:4096, 8:16384, 16:32768. string 1:2048
--'idle-timeout' <'idle-timeout'> DigitalOcean MicroVM idle timeout before auto-pause (for example 15m, maximum 4h). string 15m
--'edge-auth-only' DigitalOcean MicroVM only. Skip the per-agent AUTH_TOKEN and rely on the team microvm:access token. boolean false
--'with-tui' Bundle the on-host TUI (cast-tui command) into the image. ' + 'Off by default to keep images small and streaming fast. ' + 'Only the DigitalOcean Droplet provider currently supports the on-host TUI. MicroVMs reject this flag. boolean false

Examples

cast deploy email-agent
cast deploy email-agent --provider railway
cast deploy email-agent --provider fly
cast deploy email-agent --provider digitalocean
cast deploy email-agent --provider microvm
cast deploy email-agent --provider docker
cast deploy email-agent --provider local

Source: typescript/cast-cli/src/commands/deploy.ts

cast describe

Show agent description and details

cast describe <agent>

Arguments

NameDescriptionRequired
agent Agent name yes

Examples

cast describe email-agent

Source: typescript/cast-cli/src/commands/describe.ts

cast dev

Start agent in development mode

cast dev <agent> [flags]

Arguments

NameDescriptionRequired
agent Agent name yes

Flags

FlagDescriptionTypeDefault
--port <port> Port for A2A server integer 0
--'no-tui' Run without TUI (headless mode) boolean false

Examples

cast dev email-agent

Source: typescript/cast-cli/src/commands/dev.ts

cast edit

Edit an existing agent through an interactive TUI wizard

cast edit <agent>

Arguments

NameDescriptionRequired
agent Agent name yes

Examples

cast edit <agent-name>

Source: typescript/cast-cli/src/commands/edit.ts

cast list

List all agents

cast list

Examples

cast list

Source: typescript/cast-cli/src/commands/list.ts

cast logs

View runtime logs

cast logs <agent>

Arguments

NameDescriptionRequired
agent Agent name yes

Source: typescript/cast-cli/src/commands/logs.ts

cast migrate

Migrate to the new versioning system

cast migrate [flags]

Flags

FlagDescriptionTypeDefault
-l, --live Apply migration (default is dry-run) boolean false

Examples

cast migrate
cast migrate --live

Source: typescript/cast-cli/src/commands/migrate.ts

cast new

Create a new agent through an interactive TUI wizard

cast new

Examples

cast new

Source: typescript/cast-cli/src/commands/new.ts

cast redo

Redo previously-undone change(s) for an agent

cast redo <agent> [flags]

Arguments

NameDescriptionRequired
agent Agent name yes

Flags

FlagDescriptionTypeDefault
--steps <steps> Number of changes to redo integer 1
--message <message> Optional message for the snapshot entry string —
--json Output the redone entries as JSON boolean false

Examples

cast redo my-agent
cast redo my-agent --steps 3

Source: typescript/cast-cli/src/commands/redo.ts

cast registry

List all releases across all agents (or for a specific agent)

cast registry [agent] [flags]

Arguments

NameDescriptionRequired
agent Agent name (optional, shows detailed deployments for single agent) no

Flags

FlagDescriptionTypeDefault
--json Output as JSON boolean false

Examples

cast registry
cast registry --json
cast registry email-agent

Source: typescript/cast-cli/src/commands/registry.ts

cast release

Create a semantic release for an agent

cast release <agent> <version> [flags]

Arguments

NameDescriptionRequired
agent Agent name yes
version Semantic version (e.g., 1.6, 2.0.0) yes

Flags

FlagDescriptionTypeDefault
--message <message> Release message string —

Examples

cast release my-agent 1.6
cast release my-agent 1.6 --message "Added feature"

Source: typescript/cast-cli/src/commands/release.ts

cast releases

List all releases of an agent

cast releases <agent> [flags]

Arguments

NameDescriptionRequired
agent Agent name yes

Flags

FlagDescriptionTypeDefault
--json Output as JSON boolean false

Examples

cast releases my-agent
cast releases my-agent --json

Source: typescript/cast-cli/src/commands/releases.ts

cast rename

Rename an existing agent

cast rename <currentName> [newName]

Arguments

NameDescriptionRequired
currentName Current agent name yes
newName New agent name no

Examples

cast rename old-name new-name

Source: typescript/cast-cli/src/commands/rename.ts

cast restore

Restore an agent to a previous release

cast restore <agent> [flags]

Arguments

NameDescriptionRequired
agent Agent name yes

Flags

FlagDescriptionTypeDefault
--release <release> Restore to a specific release version string —

Examples

cast restore my-agent --release 1.0

Source: typescript/cast-cli/src/commands/restore.ts

cast shutdown

Shut down a deployed agent (destroy remote resources)

cast shutdown <agent> [flags]

Arguments

NameDescriptionRequired
agent Agent name or deployment SHA yes

Flags

FlagDescriptionTypeDefault
--force Skip confirmation prompt boolean false

Examples

cast shutdown email-agent
cast shutdown abc123  # Shutdown by deployment SHA
cast shutdown email-agent --force

Source: typescript/cast-cli/src/commands/shutdown.ts

cast stop

Stop a running agent

cast stop <agent> [flags]

Arguments

NameDescriptionRequired
agent Agent name yes

Flags

FlagDescriptionTypeDefault
--force Force kill (SIGKILL instead of SIGTERM) boolean false

Examples

cast stop email-agent
cast stop email-agent --force

Source: typescript/cast-cli/src/commands/stop.ts

cast undo

Undo the last change(s) for an agent

cast undo <agent> [flags]

Arguments

NameDescriptionRequired
agent Agent name yes

Flags

FlagDescriptionTypeDefault
--steps <steps> Number of changes to undo integer 1
--message <message> Optional message for the snapshot entry string —
--json Output the undone entries as JSON boolean false

Examples

cast undo my-agent
cast undo my-agent --steps 3
cast undo my-agent --steps 3 --message "Back to a working state"

Source: typescript/cast-cli/src/commands/undo.ts

cast update

Update agent configuration

cast update <agent> [flags]

Arguments

NameDescriptionRequired
agent Agent name yes

Flags

FlagDescriptionTypeDefault
--model <model> Update LLM model (e.g., openrouter/anthropic/claude-3.7-sonnet) string —
--description <description> Update agent description string —
--version <version> Update agent version (e.g., 1.1.0) string latest
--instructions <instructions> Update system prompt from a file path string —
--'instructions-text' <'instructions-text'> Update system prompt directly from command line text string —
--'add-tool' <'add-tool'> Add built-in tool (bash, read, glob) string —
--'remove-tool' <'remove-tool'> Remove built-in tool (bash, read, glob) string —
--'add-principle' <'add-principle'> Add a principle to the agent harness string —
--'remove-principle' <'remove-principle'> Remove a principle from the agent harness by exact text match string —
--permission <permission> Set a permission (format: tool=level, e.g., bash=always-allow) string —
--'remove-permission' <'remove-permission'> Remove a permission by tool name string —
--'python-version' <'python-version'> Update runtime Python version (e.g., 3.11, 3.12) string —
--'add-requirement' <'add-requirement'> Add a Python package requirement string —
--'remove-requirement' <'remove-requirement'> Remove a Python package requirement string —
--'dry-run' Preview changes without writing to disk boolean false

Examples

cast update email-agent --model openrouter/anthropic/claude-3.7-sonnet
cast update email-agent --description "Handles incoming emails"
cast update email-agent --instructions-text "You are an email assistant."
cast update email-agent --add-tool bash --add-tool read
cast update email-agent --remove-tool glob
cast update email-agent --add-principle "Be concise" --add-principle "Ask clarifying questions"
cast update email-agent --permission bash=always-allow --permission read=ask
cast update email-agent --python-version 3.12 --add-requirement requests

Source: typescript/cast-cli/src/commands/update.ts

cast upgrade

Upgrade a deployed agent to a new version

cast upgrade <agent> [version] [flags]

Arguments

NameDescriptionRequired
agent Agent name or deployment SHA yes
version Release version to upgrade to (optional, defaults to latest) no

Flags

FlagDescriptionTypeDefault
--'list-versions' List available releases for the agent boolean false

Examples

cast upgrade email-agent
cast upgrade abc123  # Upgrade by deployment SHA
cast upgrade email-agent 1.6
cast upgrade email-agent --list-versions

Source: typescript/cast-cli/src/commands/upgrade.ts

cast version

Show the version of the cast CLI

cast version

Examples

cast version

Source: typescript/cast-cli/src/commands/version.ts

git commands

cast git commit

Commit changes to an agent repository

cast git commit <agent> [flags]

Arguments

NameDescriptionRequired
agent Agent name yes

Flags

FlagDescriptionTypeDefault
-m, --message <message> Commit message string —

Examples

cast git commit my-agent -m "Updated instructions"

Source: typescript/cast-cli/src/commands/git/commit.ts

cast git diff

Show changes between commits or working tree

cast git diff <agent> [ref] [flags]

Arguments

NameDescriptionRequired
agent Agent name yes
ref Commit reference (optional) no

Flags

FlagDescriptionTypeDefault
--staged Show staged changes boolean false
--file <file> Show diff for specific file string —

Examples

cast git diff my-agent
cast git diff my-agent HEAD~1
cast git diff my-agent --staged

Source: typescript/cast-cli/src/commands/git/diff.ts

cast git init

Initialize a Git repository for an agent

cast git init <agent>

Arguments

NameDescriptionRequired
agent Agent name yes

Examples

cast git init my-agent

Source: typescript/cast-cli/src/commands/git/init.ts

cast git log

Show commit history for an agent

cast git log <agent> [flags]

Arguments

NameDescriptionRequired
agent Agent name yes

Flags

FlagDescriptionTypeDefault
-n, --count <count> Number of commits to show integer 10

Examples

cast git log my-agent
cast git log my-agent -n 20

Source: typescript/cast-cli/src/commands/git/log.ts

cast git push

Push commits to the remote repository

cast git push <agent> [flags]

Arguments

NameDescriptionRequired
agent Agent name yes

Flags

FlagDescriptionTypeDefault
--remote <remote> Remote name string origin
--branch <branch> Branch name string main

Examples

cast git push my-agent
cast git push my-agent origin main

Source: typescript/cast-cli/src/commands/git/push.ts

cast git remote

Manage Git remotes for an agent

cast git remote <agent> <action> [name] [url] [flags]

Arguments

NameDescriptionRequired
agent Agent name yes
action Action: add, create, list, remove yes
name Remote name (e.g., origin) no
url Remote URL (for add action) no

Flags

FlagDescriptionTypeDefault
--visibility <visibility> Repository visibility for create (private/public) string
options: private, public
private

Examples

cast git remote my-agent list
cast git remote my-agent add origin https://github.com/user/repo.git
cast git remote my-agent create origin
cast git remote my-agent remove origin

Source: typescript/cast-cli/src/commands/git/remote.ts

cast git status

Show the working tree status of an agent

cast git status <agent>

Arguments

NameDescriptionRequired
agent Agent name yes

Examples

cast git status my-agent

Source: typescript/cast-cli/src/commands/git/status.ts

meta commands

cast meta test

Run meta-builder tests

cast meta test [flags]

Flags

FlagDescriptionTypeDefault
--scenario <scenario> Run specific scenario string —
--verbose Show full output boolean false

Examples

cast meta test
cast meta test --scenario create-simple
cast meta test --verbose

Source: typescript/cast-cli/src/commands/meta/test.ts

session commands

cast session delete

Delete a session

cast session delete <identifier> [flags]

Arguments

NameDescriptionRequired
identifier Session id (or name) yes

Flags

FlagDescriptionTypeDefault
-f, --force Skip confirmation prompt boolean false

Examples

cast delete 01JABC…
cast delete my-session --force

Source: typescript/cast-cli/src/commands/session/delete.ts

cast session export

Export a session to a JSON file

cast session export <identifier> [flags]

Arguments

NameDescriptionRequired
identifier Session id (or name) yes

Flags

FlagDescriptionTypeDefault
--out <out> Output path (defaults to <agent>-<id>.json in cwd) string —

Examples

cast export 01JABC…
cast export 01JABC… --out ~/backup.json

Source: typescript/cast-cli/src/commands/session/export.ts

cast session fork

Fork a session into a new one

cast session fork <identifier> [flags]

Arguments

NameDescriptionRequired
identifier Session id (or name) to fork yes

Flags

FlagDescriptionTypeDefault
--name <name> Name for the forked session string —

Examples

cast fork 01JABC…
cast fork 01JABC… "alt approach"

Source: typescript/cast-cli/src/commands/session/fork.ts

cast session import

Import a session from a JSON file

cast session import <file> [flags]

Arguments

NameDescriptionRequired
file JSON file to import yes

Flags

FlagDescriptionTypeDefault
--'keep-id' Keep the original session id (default: assign a new id) boolean false

Examples

cast import ./session.json
cast import ./session.json --keep-id

Source: typescript/cast-cli/src/commands/session/import.ts

cast session index

Manage conversation sessions

cast session index

Examples

cast session list
cast session show <id|name>
cast session new <agent>
cast session resume <id|name>
cast session rename <id> <name>
cast session fork <id> [name]
cast session delete <id>
cast session export <id> [--out file]
cast session import <file>
cast session prune [--days N]

Source: typescript/cast-cli/src/commands/session/index.ts

cast session list

List saved conversation sessions

cast session list [flags]

Flags

FlagDescriptionTypeDefault
--agent <agent> Filter by agent name string —
--limit <limit> Maximum sessions to show integer 50
--'include-ended' Include ended sessions (default: true) boolean true
--json Output as JSON boolean false

Examples

cast list
cast list --agent my-agent
cast list --json

Source: typescript/cast-cli/src/commands/session/list.ts

cast session new

Create a new conversation session

cast session new <agent> [flags]

Arguments

NameDescriptionRequired
agent Agent name yes

Flags

FlagDescriptionTypeDefault
--name <name> Optional name for the session string —
--mode <mode> Mode at session start string
options: plan, build
build
--'ui-mode' <'ui-mode'> UI mode at session start string
options: dev, production, on-host
dev
--json Output the new session as JSON boolean false

Examples

cast new my-agent
cast new my-agent --name "auth experiment"

Source: typescript/cast-cli/src/commands/session/new.ts

cast session prune

Delete ended sessions older than N days (default: 30)

cast session prune [flags]

Flags

FlagDescriptionTypeDefault
--days <days> Cutoff in days. Sessions ended more than this many days ago are deleted. integer 30
-f, --force Skip confirmation prompt boolean false

Examples

cast prune
cast prune --days 7

Source: typescript/cast-cli/src/commands/session/prune.ts

cast session rename

Rename a session

cast session rename <identifier> <name>

Arguments

NameDescriptionRequired
identifier Session id (or current name) yes
name New name yes

Examples

cast rename 01JABC… "auth experiment"

Source: typescript/cast-cli/src/commands/session/rename.ts

cast session resume

Resume a session in the TUI

cast session resume <identifier>

Arguments

NameDescriptionRequired
identifier Session id (or name) yes

Examples

cast resume 01JABC…
cast resume my-session

Source: typescript/cast-cli/src/commands/session/resume.ts

cast session show

Print a session transcript

cast session show <identifier>

Arguments

NameDescriptionRequired
identifier Session id (or name) yes

Examples

cast show 01JABC…
cast show my-session

Source: typescript/cast-cli/src/commands/session/show.ts

Known models

The cast update command's --model flag accepts any valid OpenRouter model ID. The list below is a curated subset; the source of truth is KNOWN_MODELS in typescript/cast-cli/src/commands/update.ts.

See the cast update reference for the full flag list.