> ## 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 Overview

> Overview, project configuration, and troubleshooting for the Guava CLI

`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. Projects can be written in Python or TypeScript/Node — the base image you pick determines the runtime. The Guava SDK is included in the project template.

## Quick reference

| Command | Description |
| - | - |
| `guava login` | Authenticate the CLI |
| `guava create` | Scaffold a new project |
| `guava run` | Run the agent locally |
| `guava deploy up` | Build and deploy |
| `guava deploy logs` | View runtime logs |
| `guava conversations` | Browse past calls, transcripts, and recordings |

See [CLI commands](https://docs.goguava.ai/cli-reference/commands.md) for the full list, including deployment management, phone numbers, orgs, campaigns, and WebRTC codes.

## Targeting a project

Most commands take an optional positional argument that tells the CLI **which project** to act on. If you omit it, the CLI uses the **current directory** — so running commands from inside your project folder always works. There are two flavors:

| Flavor | Accepts | Used by |
| - | - | - |
| `[dir]` | A path to the project directory (defaults to `.`). | `run`, `deploy up`, `deploy scale`, `deploy build-logs`, `deploy changed`, `numbers buy`, `update` |
| `[target]` | A project directory (its `guava.toml` is read to find the project) **or** a project ID — the `gp-…` value shown by `guava deploy list`. | `deploy down`, `deploy status`, `deploy logs`, `deploy purge` |

The difference: `[dir]`-style commands need your project files on disk (they build, read config, or run code locally), so they only accept a path. `[target]`-style commands act on an already-deployed project, so they also accept a project ID — letting you manage a deployment from anywhere without the source checked out.

> [!NOTE]
>
> A `[dir]` argument that isn't a real directory silently falls back to the current directory. Double-check the path if a command seems to act on the wrong project.

## The `guava.toml` file

Every Guava project has a `guava.toml` file in its root directory, created by `guava create` or `guava deploy up`. It stores the project's configuration and deployment state. The CLI reads it to identify the project and track deployments.

> [!NOTE]
>
> Projects created with CLI versions 0.29.0 and lower will have a JSON `.guava` file. The CLI will automatically migrate to the new `guava.toml` on the next save.

```toml guava.toml theme={null}
project_id = "auto-generated unique ID"
name = "your project name"
base_image = "python-sandbox:3.14"  # python-sandbox:* (Python) | node-sandbox:* (TypeScript/Node)
tier = "guava-seed"           # guava-seed | guava-fruit | guava-tree
replicas = 1
phone_number = "+15555555555"  # set by guava numbers buy or guava create --phone
call_direction = "inbound"     # inbound | outbound
org_id = "..."
```

## Instance tiers

| Tier | CPU | Memory | Use case |
| - | - | - | - |
| `guava-seed` | 1 | 1Gi | Development / testing |
| `guava-fruit` | 2 | 2Gi | Standard production |
| `guava-tree` | 4 | 4Gi | High-performance workloads |

## Base images & dependencies

When you create a project, you choose a base image. During deployment, your code and dependencies are built on top of this image to produce the final container that runs in the cloud. You can change the base image later with `guava update`.

The base image also determines the project runtime: `python-sandbox:*` images run Python, `node-sandbox:*` images run TypeScript/Node.

Available base images:

* `python-sandbox:3.14`
* `python-sandbox:3.13`
* `python-sandbox:3.12`
* `python-sandbox:3.11`
* `python-sandbox:3.10`
* `node-sandbox:26`
* `node-sandbox:24`
* `node-sandbox:22`

## Dependency detection

During the build, the system installs your dependencies automatically based on the files present in your project root. It checks each set of files in order and uses the first match.

**Python:**

| Files present | What happens |
| - | - |
| `uv.lock` + `pyproject.toml` | Installs with `uv sync --frozen` (locked, reproducible) |
| `poetry.lock` + `pyproject.toml` | Installs with `uv sync` |
| `pyproject.toml` (alone) | Installs with `uv sync` |
| `requirements.txt` | Installs with `uv pip install -r requirements.txt` |
| `requirements.in` | Installs with `uv pip install -r requirements.in` |

**Node / TypeScript:**

| Files present | What happens |
| - | - |
| `pnpm-lock.yaml` | Installs with `pnpm install --frozen-lockfile --prod` |
| `yarn.lock` | Installs with `yarn install --immutable` (Yarn Berry — Yarn Classic 1.x is not supported) |
| `package-lock.json` | Installs with `npm ci --omit=dev` |
| `package.json` (alone) | Installs with `npm install --omit=dev` |

For local Node runs (`guava run`), also run `npm install` (or `pnpm install` / `yarn install`) first so `node_modules` exists.

## Troubleshooting

* **"Please run `guava login`"** — Your session has expired or you haven't logged in yet. Run `guava login` to re-authenticate.
* **"No main.py / main.ts found"** — `deploy up` requires an entry point in your project directory (`main.py` for Python, `main.ts` for Node). Make sure you're running the command from the right folder.
* **Deploy didn't pick up my changes** — If nothing changed since the last deploy, the build step is skipped automatically. Use `guava deploy up --rebuild` to force a full rebuild.
* **Build failed** — Run `guava deploy build-logs` to see the full build output and diagnose the issue.
* **Missing files in deployment** — `deploy up` excludes `guava.toml`, hidden files/dirs, `__pycache__`, and `node_modules` from the upload. Make sure your files aren't in an excluded path.
* **Dependencies not installing** — The build system auto-detects dependencies from your manifest/lockfiles. For Python that's `pyproject.toml`, `requirements.txt`, `uv.lock`, `poetry.lock`, or `requirements.in`; for Node it's `package.json`, `package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`. Make sure one is present in your project root. For local Node runs, also run `npm install` so `node_modules` exists.

## Example

```bash theme={null}
# Log in (opens browser)
guava login

# Create a new project
guava create my-agent --direction inbound

# Run locally
cd my-agent
guava run

# Deploy the project
guava deploy up

# Scale to 3 replicas
guava deploy scale 3

# View runtime logs
guava deploy logs -n 50

# Browse recent conversations
guava conversations list --direction inbound -n 20

# Download a call recording
guava conversations recording <call_id> -o call.wav

# Tear down
guava deploy down
```


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