CLI reference

guv is a single static binary for macOS, Linux and Windows. Everything it does goes through the public API, so anything you can do here, an agent can do through MCP, and vice versa.

Install

# macOS and Linux
brew install guv

# Windows
scoop install guv

# Anywhere with Node.js
npx guv

# Script (checksums are signed)
curl -fsSL https://guv.dev/install.sh | sh

Then sign in. The CLI opens your browser and you confirm with your passkey:

guv login

Flags every command accepts

Flag	What it does
--json	Machine-readable output with a stable schema. Agents should always use it.
--yes	Answer yes to confirmations. Dangerous actions still need a typed confirmation or a human approval.
--no-input	Never prompt. Fails instead, with a clear error, if input would be needed.
--project, --env	Choose the project and environment. Defaults come from the linked directory.

Exit codes

Exit codes are stable, so scripts and agents can react without parsing text.

Code	Meaning
0	success
1	not signed in
2	the request or file is not valid
3	forbidden or denied by policy
4	approval required
5	quota or spend cap
10	temporary, safe to retry

When a command exits with 4, an approval request is waiting for a human. See approval_required.

guv login

Signs you in through your browser with the OAuth device flow. The CLI stores a one-hour access token and a refresh token in your operating system’s keychain, never in a dotfile.

guv login

API:

• guv login --dev calls Sign in without a passkey (development only) (POST /v1/auth/dev-login)
• guv login calls Start the CLI device flow (RFC 8628) (POST /v1/auth/device/code)

guv logout

Signs out and removes the stored tokens from your keychain.

guv logout

API:

• guv logout calls Sign out the current session (POST /v1/auth/logout)

guv whoami

Shows who you are signed in as, your workspace and your role.

guv whoami

API:

• guv whoami calls Who am I (GET /v1/me)

guv init

Looks at the current repository, detects the stack and writes a starter guv.yaml. It then links the directory to a Guv project.

guv init

API:

• guv init calls Detect the stack of a repository and suggest a guv.yaml (POST /v1/workspaces/{workspace}/github/detect)

guv up

Deploys the current directory without needing git. The CLI uploads a source tarball and streams a friendly build log.

guv up

guv deploy

Deploys a service to an environment from its linked repository. Use --wait to block until the deployment is live or has failed.

guv deploy --service web --env production [--wait]

API:

• guv deploy calls Deploy (POST /v1/projects/{project}/environments/{environment}/services/{service}/deployments). In environments with protection turned on (usually production), changes by agents and by roles outside approver_roles return approval_required.

guv status

One screen for the whole project: health, recent deploys, spend this month and the Safety Centre grade.

guv status

API:

• guv status --api calls Check API health (GET /v1/health)
• guv status calls Everything about a project in one call (GET /v1/projects/{project}/status)

guv logs

Searches and tails logs. -f follows live output; --since and --grep narrow it down.

guv logs -f --service api --since 10m [--grep "error"]

API:

• guv logs calls Search logs (GET /v1/projects/{project}/logs)
• guv logs -f calls Live tail (Server-Sent Events) (GET /v1/projects/{project}/logs/tail)

guv run

Runs a local command with the environment’s variables injected, so you never need a .env file. Uses non-production variables unless you say otherwise.

guv run -- <cmd>

guv shell

Opens a short-lived debug machine with the same environment as the service. Every session is audited. It is off for special-category production projects unless approved.

guv shell --service api

guv db connect

Opens psql to a database through a short-lived, audited tunnel. Production needs approval.

guv db connect main

API:

• guv db connect calls Connection credentials (gated, audited) (GET /v1/projects/{project}/environments/{environment}/databases/{database}/connection). In environments with protection turned on (usually production), changes by agents and by roles outside approver_roles return approval_required.

guv db branch

Makes a copy-on-write branch of a database in seconds, with masking rules applied for personal data.

guv db branch main --name feature-x

API:

• guv db branch calls Branch a database (copy-on-write clone, masked) (POST /v1/projects/{project}/environments/{environment}/databases/{database}/branches)

guv secrets set

Sets a secret. The CLI prompts for the value, so it never lands in your shell history. Secrets are write-only: nobody can read them back, including you.

guv secrets set

API:

• guv secrets set calls Set a secret (write-only) (POST /v1/projects/{project}/environments/{environment}/secrets). In environments with protection turned on (usually production), changes by agents and by roles outside approver_roles return approval_required.

guv secrets list

Lists secret names and metadata. Values are never shown.

guv secrets list

API:

• guv secrets list calls List secrets (names and metadata only) (GET /v1/projects/{project}/environments/{environment}/secrets)

guv secrets unset

Removes a secret from an environment.

guv secrets unset

API:

• guv secrets unset calls Unset a secret (DELETE /v1/projects/{project}/environments/{environment}/secrets/{secret}). In environments with protection turned on (usually production), changes by agents and by roles outside approver_roles return approval_required.

guv secrets rotate

Rotates a secret that Guv manages, such as a database password, and redeploys the services that use it.

guv secrets rotate

API:

• guv secrets rotate calls Rotate a secret to a new value (POST /v1/projects/{project}/environments/{environment}/secrets/{secret}/rotate). In environments with protection turned on (usually production), changes by agents and by roles outside approver_roles return approval_required.

guv domains add

Adds a custom domain and prints the DNS records to create, with instructions for your registrar.

guv domains add

API:

• guv domains add calls Add a custom domain (POST /v1/projects/{project}/environments/{environment}/domains). In environments with protection turned on (usually production), changes by agents and by roles outside approver_roles return approval_required.

guv domains verify

Checks DNS and ownership, then issues the certificate.

guv domains verify

API:

• guv domains verify calls Check DNS now (POST /v1/projects/{project}/environments/{environment}/domains/{domain}/verify)

guv domains list

Lists domains and their certificate status.

guv domains list

API:

• guv domains list calls List domains (GET /v1/projects/{project}/environments/{environment}/domains)

guv plan

Compares guv.yaml with what is running and prints the changes in plain English, with the monthly cost difference.

guv plan

API:

• guv plan calls Plan guv.yaml against live state (POST /v1/projects/{project}/manifest/plan)

guv apply

Applies a plan. Nothing is ever deleted because it disappeared from the file: removed databases and volumes are kept and shown as orphaned.

guv apply

API:

• guv apply calls Apply a plan (POST /v1/projects/{project}/manifest/apply). In environments with protection turned on (usually production), changes by agents and by roles outside approver_roles return approval_required.

guv validate

Checks guv.yaml against the schema and prints every problem with its line number.

guv validate

API:

• guv validate calls Validate guv.yaml (schema, references, policy) (POST /v1/projects/{project}/manifest/validate)

guv pull

Writes the live configuration of a project out as guv.yaml.

guv pull

API:

• guv pull calls Export live state as guv.yaml (pull / eject) (GET /v1/projects/{project}/manifest)

guv import

Converts railway.json, render.yaml, fly.toml, a Heroku Procfile or app.json, or a Compose file into guv.yaml.

guv import

guv rollback

Puts an earlier deployment back live, as a new deployment, so history is never rewritten.

guv rollback --service web [--to d-123]

API:

• guv rollback calls Roll back to this deployment (POST /v1/deployments/{deployment_id}/rollback). In environments with protection turned on (usually production), changes by agents and by roles outside approver_roles return approval_required.

guv spend

Shows spend this month against your cap. --forecast projects the month end.

guv spend [--forecast]

API:

• guv spend calls Workspace spend this month, forecast and per-project breakdown (GET /v1/workspaces/{workspace}/spend)

guv doctor

Diagnoses common failures and explains them in plain English, with the command that fixes each one.

guv doctor

API:

• guv doctor calls Why a deployment failed and how to fix it (GET /v1/deployments/{deployment_id}/explanation)

guv setup agent

Installs the Guv skill and rules into Claude Code, Cursor, Codex and other coding agents, so they know how to deploy, read logs, set secrets without echoing them, and handle approval requests.

guv setup agent

guv approve

Approves an action an agent asked for. You confirm with your passkey; the agent never sees a credential.

guv approve <id>

API:

• guv approve calls Approve a request (passkey required) (POST /v1/approvals/{approval_id}/approve)

guv tokens create-agent

Creates an agent token with scopes, environments, a daily spend budget and an expiry. The token is shown once.

guv tokens create-agent

API:

• guv tokens create-agent calls Create an agent token (POST /v1/workspaces/{workspace}/agent-tokens)

guv approvals wait

Waits for a pending approval and exits with its outcome. Useful in scripts and for agents.

guv approvals wait

API:

• guv approvals wait calls Get an approval request (GET /v1/approvals/{approval_id})

guv projects list

Lists the projects in your workspace.

guv projects list

API:

• guv projects list calls List projects (GET /v1/workspaces/{workspace}/projects)

guv env create

Creates an environment, such as staging.

guv env create

API:

• guv env create calls Create an environment (POST /v1/projects/{project}/environments)

guv services update

Changes a service’s settings.

guv services update

API:

• guv services update calls Update a service’s base settings (PATCH /v1/projects/{project}/services/{service}). In environments with protection turned on (usually production), changes by agents and by roles outside approver_roles return approval_required.

guv restart

Restarts a service without a new build.

guv restart

API:

• guv restart calls Restart the running deployment (POST /v1/projects/{project}/environments/{environment}/services/{service}/restart). In environments with protection turned on (usually production), changes by agents and by roles outside approver_roles return approval_required.

guv variables set

Sets a plain variable. Values are visible to project members, so use guv secrets set for anything sensitive.

guv variables set

API:

• guv variables set calls Set plain variables (create or replace) (POST /v1/projects/{project}/environments/{environment}/variables). In environments with protection turned on (usually production), changes by agents and by roles outside approver_roles return approval_required.

guv db create

Creates a managed database in an environment.

guv db create

API:

• guv db create calls Create a database (POST /v1/projects/{project}/environments/{environment}/databases). In environments with protection turned on (usually production), changes by agents and by roles outside approver_roles return approval_required.

guv mcp

Runs the Guv MCP server over stdio, using your CLI sign-in. Point your AI client at guv mcp.

guv mcp