import { CodeBlock } from '../views/docs/CodeBlock';
import { Callout, Prose, NextLink } from '../views/docs/prose';

## CLI Reference

`guava` is the primary interface for working with Guava. It handles project scaffolding, deployment, phone number provisioning, and deployment lifecycle management (logs, status, teardown). The Guava SDK is installed automatically as part of the project template.

### Quick reference

| Command | Description |
|---------|-------------|
| `guava login` | Authenticate via OAuth |
| `guava create <name>` | Scaffold a new project |
| `guava deploy up` | Build and deploy (add `--rebuild` to force) |
| `guava deploy down` | Stop a deployment |
| `guava deploy status` | Check deployment state |
| `guava deploy logs [-n N]` | View runtime logs |
| `guava deploy build-logs` | Get build log URL |
| `guava deploy ls` | List all deployments |
| `guava deploy update` | Reconfigure project settings |
| `guava deploy changed` | Check if code changed since last deploy |
| `guava numbers buy` | Provision a phone number |

### Command reference

#### `guava login`

No parameters. Opens a browser to log in. Credentials are stored locally in `~/.config/guava/config.json` and refreshed automatically on subsequent CLI calls.

#### `guava create`

| Name | Type | Required | Description |
|------|------|----------|-------------|
| name | string | No | Optional project name. If omitted, prompted interactively. Used as the directory name and the generated `CallController` class name. |

#### `guava deploy up`

| Name | Type | Required | Description |
|------|------|----------|-------------|
| dir | string | No | Optional path to the project directory. Defaults to the current directory. |
| --rebuild | flag | No | Force a fresh build even if code has not changed. |

#### `guava deploy down`

| Name | Type | Required | Description |
|------|------|----------|-------------|
| target | string | No | Optional project name or directory path. Defaults to the current directory. |
| --id | string | No | Optional task ID to stop directly. |

#### `guava deploy ls`

No parameters. Lists all deployments for the authenticated user as a table (NAME, NUMBER, ACTIVE, ID).

#### `guava deploy status`

| Name | Type | Required | Description |
|------|------|----------|-------------|
| target | string | No | Optional project name or directory path. If omitted, behaves like `deploy ls`. |

#### `guava deploy logs`

| Name | Type | Required | Description |
|------|------|----------|-------------|
| target | string | No | Optional project name or directory path. Defaults to the current directory. |
| -n, --tail | integer | No | Number of log lines to retrieve (default 200, max 1000). |

#### `guava deploy build-logs`

| Name | Type | Required | Description |
|------|------|----------|-------------|
| target | string | No | Optional project name or directory path. Defaults to the current directory. |
| --id | string | No | Optional Cloud Build ID to look up directly. |

#### `guava deploy update`

| Name | Type | Required | Description |
|------|------|----------|-------------|
| target | string | No | Optional project name or directory path. Defaults to the current directory. |

Re-prompts for all configuration fields (name, base image, tier) with current values shown as defaults.

#### `guava deploy changed`

| Name | Type | Required | Description |
|------|------|----------|-------------|
| target | string | No | Optional project name or directory path. Defaults to the current directory. |

Checks whether project files have changed since the last deploy.

#### `guava numbers buy`

| Name | Type | Required | Description |
|------|------|----------|-------------|
| dir | string | No | Optional path to the project directory. Defaults to the current directory. |

Purchases a phone number and stores it in `.guava`. On the next deploy, the number is available to your code via the `GUAVA_AGENT_NUMBER` environment variable.

### The `.guava` file

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

<Callout>
  <span className="text-primary font-semibold">Do not edit this file manually.</span> Use `guava deploy update` to change settings. Manually editing `.guava` can put your project into an inconsistent state and cause deploy failures.
</Callout>

<Callout>
  <span className="text-primary font-semibold">Commit this file to git.</span> If you delete it or leave it out of version control, the CLI won't be able to find your project or resume previous deployments.
</Callout>

<CodeBlock
  filename=".guava"
  language="json"
  code={`{
  "project_id": "auto-generated unique ID for your project",
  "name": "your project name",
  "base_image": "base container image, e.g. python-sandbox:3.14",
  "tier": "instance tier: guava-seed, guava-fruit, or guava-tree",
  "phone_number": "assigned phone number (set by guava numbers buy)",
  "task_id": "current deployment ID (managed by the CLI)",
  "build_id": "current build artifact ID (managed by the CLI)",
  "cloud_build_id": "current cloud build job ID (managed by the CLI)",
  "bundle_hash": "hash of your code from the last deploy (managed by the CLI)"
}`}
/>

### 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 deploy update`.

Available base images:

- `python-sandbox:3.14`
- `python-sandbox:3.13`
- `python-sandbox:3.12`
- `python-sandbox:3.11`
- `python-sandbox:3.10`

Dependencies are installed from `pyproject.toml`, `requirements.txt`, `uv.lock`, or `poetry.lock`.

### 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 found"** — `deploy up` requires a `main.py` in your project directory. 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`, 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 `pyproject.toml`, `requirements.txt`, `uv.lock`, or `poetry.lock`. Make sure one of these is present in your project root.

### Example

<CodeBlock
  filename="terminal"
  language="bash"
  code={`# Log in (opens browser)
guava login

# Create a new project
guava create my-agent

# Deploy the project
cd my-agent
guava deploy up

# Check status
guava deploy status

# View runtime logs
guava deploy logs -n 50

# List all deployments
guava deploy ls

# Buy a phone number for the project
guava numbers buy

# Tear down
guava deploy down`}
/>

<NextLink section="webrtc-widgets" label="WebRTC Widgets" />