## 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. `[{