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

guava deploy up

guava deploy down

guava deploy ls

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

guava deploy status

guava deploy logs

guava deploy build-logs

guava deploy update

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

guava deploy changed

Checks whether project files have changed since the last deploy.

guava numbers buy

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.

{
"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

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

# 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