cli reference.md

CLI Reference

guava is the primary interface for working with Guava. It handles authentication, project scaffolding, local runs, deployment, phone number provisioning, conversation history, org management, outbound campaigns, and WebRTC widget codes. The Guava SDK is installed automatically as part of the project template.

Quick reference

Command Description
guava login [--no-launch-browser] Authenticate via OAuth (browser-based)
guava logout Clear stored credentials
guava create [name] [flags…] Scaffold a new project (see guava create below)
guava run [target] [-- args…] Run the agent locally with uv
guava update [flags…] Update project configuration (replaces deploy update)
guava self-upgrade Upgrade the guava CLI to the latest version
guava deploy up [dir] [--rebuild] Build and deploy
guava deploy down [target] [--id ID] Stop a deployment
guava deploy scale <replicas> [dir] Scale a running deployment
guava deploy status [target] Check deployment state
guava deploy logs [target] [-n N] Runtime logs (default 200, max 1000)
guava deploy build-logs [target] [--id ID] Get build log URL
guava deploy list (alias ls) List all deployments
guava deploy changed [dir] Check whether code changed since last deploy
guava numbers list (alias ls) List owned phone numbers
guava numbers buy [dir] Provision a phone number for this project
guava conversations list [filters…] List conversations (calls)
guava conversations get <call_id> Show conversation details
guava conversations transcript <call_id> Show conversation transcript
guava conversations recording <call_id> [-o path] Download recording (WAV)
guava org / guava org list List organizations you belong to
guava org use [org_id] Switch active org (interactive if omitted)
guava campaigns list (alias ls) List outbound campaigns
guava campaigns show <code> Campaign details and status counts
guava campaigns pause <code> / resume <code> / delete <code> Lifecycle controls
guava campaigns add-contacts <code> <file> [flags…] Upload contacts
guava widget [--ttl SEC] Mint a WebRTC widget code

Command reference

guava login

Authenticates the CLI against Guava via OAuth. Opens your default browser to a sign-in page and stores the resulting credentials locally so subsequent commands can call the API on your behalf.

Name Type Required Description
--no-launch-browser flag No Print the login URL instead of opening a browser.

guava logout

Clears stored credentials. No parameters.

guava create

Scaffolds a new Guava project on disk — generates main.py, pyproject.toml, PRD.md, README.md, and the guava.toml config — and (unless --skip-deps is set) runs uv sync to install dependencies. For outbound projects it also creates the matching campaign on the server.

guava create runs in interactive mode by default — the CLI prompts for anything you don't pass. In non-interactive mode (when stdin is not a TTY, or when you pass --no-prompt), there are no prompts: required flags must be supplied or the command errors, and optional flags fall back to documented defaults.

Positional argument

Name Type Required Description
name string No Project path or name. Defaults to current directory.

Non-interactive mode flags — in interactive mode you can omit any of these and the CLI will prompt; in non-interactive mode they behave as noted under "Required".

Name Type Required (non-interactive) Description
--no-prompt flag No Force non-interactive mode. Auto-enabled when stdin is not a TTY.
--direction inbound | outbound Yes Call direction for the project. The only flag that has no default.
--base-image string No Sandbox base image. Default python-sandbox:3.14.
--tier seed | fruit | tree No Instance tier. Default seed.
--replicas integer No Number of pod replicas. Default 1.

Inbound-only (--direction inbound):

Name Type Required (non-interactive) Description
--phone string No Phone source: E.164 number, any (first owned number), or buy (provision a new one).

Outbound-only (--direction outbound):

Name Type Required (non-interactive) Description
--calling-windows JSON Yes E.g. `[{