> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goguava.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI commands

> Full reference for every Guava CLI command and its flags

Flags and arguments for every `guava` command. For an overview, project targeting, and configuration, see the [CLI overview](https://docs.goguava.ai/cli-reference/cli-overview.md).

## `guava login`

Authenticate the CLI with Guava.

```bash theme={null}
guava login [OPTIONS]
```

| Name | Type | Required | Description |
| - | - | - | - |
| `--no-launch-browser` | flag | No | Suppress automatic browser launch for the login URL |

## `guava logout`

Log the CLI out of Guava.

```bash theme={null}
guava logout
```

## `guava create`

Create a new Guava project.

Any unset flag is prompted interactively. Without a TTY (or with --no-prompt), missing required flags error and the rest fall back to the defaults noted in --help.

The base image sets the runtime. Python projects get main.py and pyproject.toml, and dependencies are installed with `uv sync`. TypeScript/Node projects get main.ts and package.json; `npm install` is offered interactively, otherwise install dependencies yourself. Both also get README.md, guava-docs.md (a reference for AI coding assistants), and guava.toml.

Outbound projects also create their campaign on the server. Passing an inbound-only flag with --direction outbound (or vice versa) is an error.

```bash theme={null}
guava create [OPTIONS] [name]
```

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `name` | string | No | `current directory` | Project path or name |
| `--no-prompt` | flag | No | | Disable interactive prompts; missing required flags will error. Auto-enabled when stdin is not a TTY |
| `--direction` | `inbound` \| `outbound` | Non-interactive | | Call direction |
| `--base-image` | string | No | `python-sandbox:3.14` | Sandbox base image. Determines the project runtime (`python-sandbox:*` → Python, `node-sandbox:*` → TypeScript/Node) |
| `--tier` | `guava-seed` \| `guava-fruit` \| `guava-tree` | No | `guava-seed` | Instance tier `guava-seed`: 1 CPU, 1Gi — Development / testing `guava-fruit`: 2 CPU, 2Gi — Standard production `guava-tree`: 4 CPU, 4Gi — High-performance workloads |
| `--replicas` | integer | No | `1` | Number of pod replicas (1-20) |

**Inbound options (with --direction inbound)**

| Name | Type | Required | Description |
| - | - | - | - |
| `--phone` | string | No | Inbound agent phone source. Accepts an E.164 number (e.g. +15555555555), `any` (pick the first number from your account), or `buy` (provision a new one). List your numbers with `guava numbers list` |

**Outbound options (with --direction outbound)**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `--campaign-name` | string | No | `project name` | Campaign name |
| `--timezone` | string | No | `detected system timezone` | Campaign timezone, as an IANA name (e.g. `America/New_York`) |
| `--origin-number` | string (repeatable) | Non-interactive | | Outbound origin phone source. Repeat for multiple. Each value accepts an E.164 number (e.g. +15555555555), `any` (pick the first number from your account), or `buy` (provision a new one). List your numbers with `guava numbers list` |
| `--max-concurrency` | integer | No | `1` | Max concurrent calls |
| `--max-attempts` | integer | No | `1` | Max attempts per recipient |
| `--retry-delay-s` | integer | No | `3600` | Seconds to wait before reattempting a recipient. Only applies when --max-attempts is above 1 |
| `--start-date` | string | No | `today` | Campaign start date (YYYY-MM-DD) |
| `--calling-windows` | string | Non-interactive | | Calling windows as a JSON array, e.g. `[{"day":"monday","start":"09:00","end":"17:00"}]` |
| `--description` | string | No | | Free-form campaign description used as outreach context |

## `guava run`

Run the agent locally.

The runtime comes from guava.toml's base\_image, or is inferred from pyproject.toml / package.json if there's no config. Python projects run `uv run main.py`; Node projects run `node --import tsx main.ts` and need `npm install` first.

```bash theme={null}
guava run [target] [-- args...]
```

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `target` | string | No | `.` | Project directory path |
| `-- args…` | string | No | | Extra arguments forwarded to the agent's entry point (pass after `--`) |

## `guava deploy`

Deploy and manage deployments.

### `guava deploy up`

Deploy the project.

```bash theme={null}
guava deploy up [OPTIONS] [dir]
```

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `dir` | string | No | `.` | Project directory path |
| `--rebuild` | flag | No | | Force a rebuild even if code hasn't changed |
| `--yes` | flag | No | | Update an existing deployment without confirming |

### `guava deploy scale`

Scale a running deployment to N replicas (1-20).

```bash theme={null}
guava deploy scale <replicas> [dir]
```

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `replicas` | integer | Yes | | Number of pod replicas |
| `dir` | string | No | `.` | Project directory path |

### `guava deploy down`

Stop a deployment.

```bash theme={null}
guava deploy down [OPTIONS] [target]
```

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `target` | string | No | `.` | Project directory or project ID (`gp-…`) |
| `--id` | string | No | | Project ID to stop directly |
| `--yes` | flag | No | | Stop the deployment without confirming |

### `guava deploy purge`

Permanently delete every trace of a project (deployments, images, bundles, build history, DB records). This cannot be undone.

```bash theme={null}
guava deploy purge [target]
```

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `target` | string | No | `.` | Project directory or project ID (`gp-…`) |

### `guava deploy list`

List all deployments.

```bash theme={null}
guava deploy list
```

Aliases: `ls`

### `guava deploy status`

Get deployment status.

```bash theme={null}
guava deploy status [target]
```

| Name | Type | Required | Description |
| - | - | - | - |
| `target` | string | No | Project directory or project ID (`gp-…`). Omit to list all deployments |

### `guava deploy logs`

Get runtime logs from the running deployment.

```bash theme={null}
guava deploy logs [OPTIONS] [target]
```

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `target` | string | No | `.` | Project directory or project ID (`gp-…`) |
| `-n` | integer | No | `200` | Number of lines to show (max 1000) |

### `guava deploy build-logs`

Get build logs (returns a signed URL).

```bash theme={null}
guava deploy build-logs [OPTIONS] [target]
```

| Name | Type | Required | Description |
| - | - | - | - |
| `target` | string | No | Project directory |
| `--id` | string | No | Cloud Build ID to fetch logs for directly |

### `guava deploy changed`

Check if project code has changed since last deploy.

```bash theme={null}
guava deploy changed [dir]
```

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `dir` | string | No | `.` | Project directory path |

## `guava numbers`

Manage phone numbers.

### `guava numbers list`

List owned phone numbers.

```bash theme={null}
guava numbers list
```

Aliases: `ls`

### `guava numbers buy`

Buy a phone number and attach it to this project.

The number is saved to guava.toml, and is available to the agent as \$GUAVA\_AGENT\_NUMBER after the next deploy.

```bash theme={null}
guava numbers buy [dir]
```

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `dir` | string | No | `.` | Project directory |

## `guava conversations`

Browse conversations (calls).

### `guava conversations list`

List conversations.

```bash theme={null}
guava conversations list [OPTIONS]
```

Aliases: `ls`

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `--direction` | string | No | | Filter by call direction: `inbound` or `outbound` |
| `--from` | string | No | | Filter by caller number (E.164) |
| `--to` | string | No | | Filter by called number (E.164) |
| `--date-from` | string | No | | Filter by start date (ISO 8601, e.g. 2026-06-01) |
| `--date-to` | string | No | | Filter by end date (ISO 8601, e.g. 2026-06-10) |
| `-n, --limit` | integer | No | `50` | Page size (1-100) |
| `--after` | string | No | | Pagination cursor (`next_cursor` from the previous page) |

### `guava conversations get`

Show conversation details.

```bash theme={null}
guava conversations get <call_id>
```

| Name | Type | Required | Description |
| - | - | - | - |
| `call_id` | string | Yes | Call ID |

### `guava conversations transcript`

Show conversation transcript.

```bash theme={null}
guava conversations transcript <call_id>
```

| Name | Type | Required | Description |
| - | - | - | - |
| `call_id` | string | Yes | Call ID |

### `guava conversations recording`

Download conversation recording (WAV).

```bash theme={null}
guava conversations recording [OPTIONS] <call_id>
```

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `call_id` | string | Yes | | Call ID |
| `-o, --output` | path | No | `<call_id>.wav` | Output file path |

## `guava org`

Manage organizations.

### `guava org list`

List organizations you belong to.

```bash theme={null}
guava org list
```

Aliases: `ls`

### `guava org use`

Switch to a different organization.

The active org determines which numbers, deployments, conversations, and campaigns the other commands act on.

```bash theme={null}
guava org use [org_id]
```

| Name | Type | Required | Description |
| - | - | - | - |
| `org_id` | string | No | Organization ID. Omit to pick interactively |

## `guava campaigns`

Manage outbound campaigns.

### `guava campaigns list`

List outbound campaigns.

```bash theme={null}
guava campaigns list
```

Aliases: `ls`

### `guava campaigns show`

Show campaign details and status counts.

```bash theme={null}
guava campaigns show <code>
```

| Name | Type | Required | Description |
| - | - | - | - |
| `code` | string | Yes | Campaign code (`gcmp-…`), shown by `guava campaigns list` |

### `guava campaigns pause`

Pause a campaign.

```bash theme={null}
guava campaigns pause [OPTIONS] <code>
```

| Name | Type | Required | Description |
| - | - | - | - |
| `code` | string | Yes | Campaign code (`gcmp-…`), shown by `guava campaigns list` |
| `--yes` | flag | No | Pause without confirming |

### `guava campaigns resume`

Resume a paused campaign.

```bash theme={null}
guava campaigns resume [OPTIONS] <code>
```

| Name | Type | Required | Description |
| - | - | - | - |
| `code` | string | Yes | Campaign code (`gcmp-…`), shown by `guava campaigns list` |
| `--yes` | flag | No | Resume without confirming |

### `guava campaigns delete`

Delete a campaign.

```bash theme={null}
guava campaigns delete <code>
```

| Name | Type | Required | Description |
| - | - | - | - |
| `code` | string | Yes | Campaign code (`gcmp-…`), shown by `guava campaigns list` |

### `guava campaigns add-contacts`

Add contacts to a campaign from a file.

Each contact requires a `phone_number` field (E.164, e.g. +15555550100). Every other field becomes an entry in the contact's `data`.

Formats (dispatched by extension):

```text theme={null}
.csv             header row with `phone_number`; other columns become string entries in `data`
.json            array: [{"phone_number": "+1...", "name": "..."}]
.jsonl/.ndjson   one JSON object per line
```

```bash theme={null}
guava campaigns add-contacts [OPTIONS] <code> <file>
```

| Name | Type | Required | Description |
| - | - | - | - |
| `code` | string | Yes | Campaign code (`gcmp-…`), shown by `guava campaigns list` |
| `file` | path | Yes | Path to contacts file (.csv \| .json \| .jsonl \| .ndjson) |
| `--allow-duplicates` | flag | No | Upload contacts even if they are already on the campaign |
| `--accept-tos` | flag | No | Confirm the contacts comply with the Terms of Service ([https://goguava.ai/terms](https://goguava.ai/terms)). Required in non-interactive mode |

## `guava webrtc`

Manage WebRTC codes.

### `guava webrtc create-code`

Create a WebRTC code and print it.

```bash theme={null}
guava webrtc create-code [OPTIONS]
```

| Name | Type | Required | Description |
| - | - | - | - |
| `--expires-in` | seconds | No | Seconds until the WebRTC code expires (omit for a permanent code) |
| `--require-token` | flag | No | Require callers to present a single-use client token, created by your backend |

### `guava webrtc create-client-token`

Create a single-use client token for a WebRTC code and print it.

```bash theme={null}
guava webrtc create-client-token [OPTIONS] <webrtc_code>
```

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `webrtc_code` | string | Yes | | The WebRTC code the token grants access to |
| `--expires-in` | seconds | No | `3600` | Seconds until the token expires if unused |

## `guava widget`

Generate an embeddable web call widget.

```bash theme={null}
guava widget [OPTIONS]
```

| Name | Type | Required | Description |
| - | - | - | - |
| `--expires-in` | seconds | No | Seconds until the WebRTC code expires (omit for a permanent code) |

## `guava say`

Generate text-to-speech (TTS) audio from input.

```bash theme={null}
guava say [OPTIONS] <input>
```

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `input` | string | Yes | | Text to synthesize |
| `-v, --voice` | `grace` \| `jack` \| `otto` \| `colin` | No | `grace` | Voice to use |
| `-l, --language` | string | No | `English` | Language to speak in |
| `-s, --sampling-rate` | `8000` \| `16000` | No | `16000` | Sampling rate in Hz |

## `guava update`

Update project configuration.

```bash theme={null}
guava update [OPTIONS] [target]
```

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `target` | string | No | `.` | Project directory path |
| `--no-prompt` | flag | No | | Disable interactive prompts; unset fields keep their current values. Auto-enabled when stdin is not a TTY |
| `--name` | string | No | | Project name |
| `--base-image` | string | No | | Sandbox base image |
| `--tier` | `guava-seed` \| `guava-fruit` \| `guava-tree` | No | | Instance tier `guava-seed`: 1 CPU, 1Gi — Development / testing `guava-fruit`: 2 CPU, 2Gi — Standard production `guava-tree`: 4 CPU, 4Gi — High-performance workloads |

## `guava self-upgrade`

Upgrade the guava CLI to the latest version.

```bash theme={null}
guava self-upgrade
```

## `guava export-cli-schema`

Print a JSON description of every command.

```bash theme={null}
guava export-cli-schema
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.