# CLI reference > Every guv command, its flags, exit codes and the API call behind it. `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 ```bash # 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: ```bash 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](/errors/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. ```bash guv login ``` **API:** - `guv login --dev` calls [Sign in without a passkey (development only)](/docs/api/auth/#sign-in-without-a-passkey-development-only) (`POST /v1/auth/dev-login`) - `guv login` calls [Start the CLI device flow (RFC 8628)](/docs/api/auth/#start-the-cli-device-flow-rfc-8628) (`POST /v1/auth/device/code`) ## guv logout Signs out and removes the stored tokens from your keychain. ```bash guv logout ``` **API:** - `guv logout` calls [Sign out the current session](/docs/api/auth/#sign-out-the-current-session) (`POST /v1/auth/logout`) ## guv whoami Shows who you are signed in as, your workspace and your role. ```bash guv whoami ``` **API:** - `guv whoami` calls [Who am I](/docs/api/me/#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. ```bash guv init ``` **API:** - `guv init` calls [Detect the stack of a repository and suggest a guv.yaml](/docs/api/git-hub/#detect-the-stack-of-a-repository-and-suggest-a-guvyaml) (`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. ```bash 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. ```bash guv deploy --service web --env production [--wait] ``` **API:** - `guv deploy` calls [Deploy](/docs/api/deployments/#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. ```bash guv status ``` **API:** - `guv status --api` calls [Check API health](/docs/api/health/#check-api-health) (`GET /v1/health`) - `guv status` calls [Everything about a project in one call](/docs/api/projects/#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. ```bash guv logs -f --service api --since 10m [--grep "error"] ``` **API:** - `guv logs` calls [Search logs](/docs/api/logs/#search-logs) (`GET /v1/projects/{project}/logs`) - `guv logs -f` calls [Live tail (Server-Sent Events)](/docs/api/logs/#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. ```bash guv run -- ``` ## 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. ```bash guv shell --service api ``` ## guv db connect Opens `psql` to a database through a short-lived, audited tunnel. Production needs approval. ```bash guv db connect main ``` **API:** - `guv db connect` calls [Connection credentials (gated, audited)](/docs/api/databases/#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. ```bash guv db branch main --name feature-x ``` **API:** - `guv db branch` calls [Branch a database (copy-on-write clone, masked)](/docs/api/databases/#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. ```bash guv secrets set ``` **API:** - `guv secrets set` calls [Set a secret (write-only)](/docs/api/secrets/#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. ```bash guv secrets list ``` **API:** - `guv secrets list` calls [List secrets (names and metadata only)](/docs/api/secrets/#list-secrets-names-and-metadata-only) (`GET /v1/projects/{project}/environments/{environment}/secrets`) ## guv secrets unset Removes a secret from an environment. ```bash guv secrets unset ``` **API:** - `guv secrets unset` calls [Unset a secret](/docs/api/secrets/#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. ```bash guv secrets rotate ``` **API:** - `guv secrets rotate` calls [Rotate a secret to a new value](/docs/api/secrets/#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. ```bash guv domains add ``` **API:** - `guv domains add` calls [Add a custom domain](/docs/api/domains/#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. ```bash guv domains verify ``` **API:** - `guv domains verify` calls [Check DNS now](/docs/api/domains/#check-dns-now) (`POST /v1/projects/{project}/environments/{environment}/domains/{domain}/verify`) ## guv domains list Lists domains and their certificate status. ```bash guv domains list ``` **API:** - `guv domains list` calls [List domains](/docs/api/domains/#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. ```bash guv plan ``` **API:** - `guv plan` calls [Plan guv.yaml against live state](/docs/api/manifest/#plan-guvyaml-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. ```bash guv apply ``` **API:** - `guv apply` calls [Apply a plan](/docs/api/manifest/#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. ```bash guv validate ``` **API:** - `guv validate` calls [Validate guv.yaml (schema, references, policy)](/docs/api/manifest/#validate-guvyaml-schema-references-policy) (`POST /v1/projects/{project}/manifest/validate`) ## guv pull Writes the live configuration of a project out as `guv.yaml`. ```bash guv pull ``` **API:** - `guv pull` calls [Export live state as guv.yaml (pull / eject)](/docs/api/manifest/#export-live-state-as-guvyaml-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`. ```bash guv import ``` ## guv rollback Puts an earlier deployment back live, as a new deployment, so history is never rewritten. ```bash guv rollback --service web [--to d-123] ``` **API:** - `guv rollback` calls [Roll back to this deployment](/docs/api/deployments/#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. ```bash guv spend [--forecast] ``` **API:** - `guv spend` calls [Workspace spend this month, forecast and per-project breakdown](/docs/api/spend/#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. ```bash guv doctor ``` **API:** - `guv doctor` calls [Why a deployment failed and how to fix it](/docs/api/deployments/#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. ```bash guv setup agent ``` ## guv approve Approves an action an agent asked for. You confirm with your passkey; the agent never sees a credential. ```bash guv approve ``` **API:** - `guv approve` calls [Approve a request (passkey required)](/docs/api/approvals/#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. ```bash guv tokens create-agent ``` **API:** - `guv tokens create-agent` calls [Create an agent token](/docs/api/agent-tokens/#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. ```bash guv approvals wait ``` **API:** - `guv approvals wait` calls [Get an approval request](/docs/api/approvals/#get-an-approval-request) (`GET /v1/approvals/{approval_id}`) ## guv projects list Lists the projects in your workspace. ```bash guv projects list ``` **API:** - `guv projects list` calls [List projects](/docs/api/projects/#list-projects) (`GET /v1/workspaces/{workspace}/projects`) ## guv env create Creates an environment, such as staging. ```bash guv env create ``` **API:** - `guv env create` calls [Create an environment](/docs/api/environments/#create-an-environment) (`POST /v1/projects/{project}/environments`) ## guv services update Changes a service's settings. ```bash guv services update ``` **API:** - `guv services update` calls [Update a service's base settings](/docs/api/services/#update-a-services-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. ```bash guv restart ``` **API:** - `guv restart` calls [Restart the running deployment](/docs/api/services/#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. ```bash guv variables set ``` **API:** - `guv variables set` calls [Set plain variables (create or replace)](/docs/api/variables/#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. ```bash guv db create ``` **API:** - `guv db create` calls [Create a database](/docs/api/databases/#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`. ```bash guv mcp ```