---
title: CLI reference
description: "Every sproutboat command, grouped by task, plus every environment variable it reads."
---

Install the CLI in each project with `npm i -D sproutboat` (or `pnpm add -D`, `bun add -d`, `yarn add -D`) to pin the version that compiles your handler, then run commands with `npx sproutboat <command>` or a `package.json` script such as `npm run deploy`. `sproutboat init` adds the dependency and the `dev`, `deploy` and `check` scripts. For quick commands outside a project, `npm i -g sproutboat` lets you type `sproutboat <command>` directly. See [Install the CLI](/docs/get-started#install-the-cli). Run `sproutboat` with no arguments for the grouped list, and a command with no arguments for its full usage. Commands that take `[dir]` default to the current directory.

## Develop

| Command | Does |
| --- | --- |
| `init [name]` | Scaffold `sproutboat.jsonc`, `src/index.js`, `.gitignore` and `package.json` in `./<name>`. `package.json` gets `sproutboat` in `devDependencies` (a caret range on the running version) and the `dev`, `deploy` and `check` scripts. An existing `package.json` keeps its fields, and a script with the same name is left alone with a warning. The next step it prints follows your package manager. |
| `check [dir]` | Validate the config and entry point without building. |
| `types [dir]` | Write `sproutboat-env.d.ts` from the config. See [Generated types](/docs/concepts/types). |
| `dev [dir] [--port <n>] [--no-watch] [--env <name>] [--env-file <file>]...` | Run the project on this machine with a local broker, rebuilding on save. Secrets come from `.dev.vars` or the `.env` files (never both), as in Wrangler; `--env-file` replaces the default `.env` set and can repeat. A declared secret with no value is a warning. |
| `run [dir] [--binary <file>] [--env-file <file>]... [--port <n>] [--data-dir <dir>] [--require <NAME,...>] [--check]` | Launch a [standalone binary](/docs/get-started/standalone#launching-with-sproutboat-run) with its port, data directory and secrets supplied at launch. A declared secret with no value fails the launch; `--check` validates without starting. |
| `build [dir] [--target host] [--standalone]` | Compile the sprout for `linux-x86_64`. `--target host` builds for this machine instead, to run locally. `--standalone` emits one executable with its bindings compiled in; see [Standalone binaries](/docs/get-started/standalone). |
| `toolchain doctor [--json]` | Report the compiler inputs, cache locations, overrides and host prerequisites, without downloading or compiling. |

## Ship

| Command | Does |
| --- | --- |
| `deploy [dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision]` | Build, create storage for bindings without an id and write the ids into `sproutboat.jsonc`, upload, and wait until the URL serves. `--dry-run` stops before upload. `--artifact` uploads a prebuilt directory. `--no-wait` skips the wait. `--no-provision` gives bindings without an id a throwaway store for this deploy only. |
| `versions list [dir]` | List deployed versions. |
| `versions view <version-id> [dir]` | Show one version's artifact and bindings. |
| `rollback <version-id> [dir]` | Make a previous version active again. |
| `tail [dir] [--format pretty\|json] [--status ok\|error\|<code>\|5xx] [--method GET,POST] [--search <text>]` | Stream the app's request events, `console.*` output and uncaught exceptions live. `--format json` writes one event per line. `tail --recent` prints the last 100 request records instead, and `tail --sprout` the running sprout's and broker's output. |
| `tail --file <log\|-> [--lines <n>] [--no-follow] [--format pretty\|json] [--status <s>] [--method <m>] [--search <text>]` | Follow the request and error records a [standalone binary](/docs/get-started/standalone#logs) writes with `SB_LOG=json`. Needs no login. |

## Storage

| Command | Does |
| --- | --- |
| `kv <list \| create \| info \| rename \| delete>` | Manage KV namespaces. `kv key`, `kv bulk` and `kv export` manage their contents; see [Manage and export KV data](/docs/storage/manage-kv-data). |
| `d1 <list \| create \| info \| rename \| delete>` | Manage D1 databases. |
| `r2 <list \| create \| info \| rename \| delete>` | Manage R2 buckets. |
| `queues <list \| create \| info \| rename \| delete>` | Manage queues. |

`create <name>` prints the new resource's id. `info`, `rename` and `delete` take the resource name. See [Storage resources](/docs/storage).

## Configure

| Command | Does |
| --- | --- |
| `domains <list \| add <host> \| verify <host> \| delete <host>> [dir]` | Manage custom domains. See [Custom domains](/docs/platform/custom-domains). |
| `secrets <list \| put <NAME> [--value <value>] \| delete <NAME>> [dir]` | Manage encrypted secrets. `put` reads the value from stdin unless `--value` is given. See [Secrets](/docs/bindings/secrets). |
| `delete [dir] [--name <project>] --yes` | Delete the project, every version, and its route. |

## Account

| Command | Does |
| --- | --- |
| `login [--api-url <url>] [--token <token>]` | Sign in with the device-code browser flow, or store a token directly. See [Get access](/docs/get-started/access). |
| `logout [--api-url <url>]` | Forget the stored credential for the active endpoint, or for `<url>`. |
| `whoami` | Show the active endpoint and the account its token belongs to. |
| `complete [bash \| zsh \| fish]` | Print a shell completion script. Defaults to `$SHELL`. |

## Environment variables

| Variable | Purpose |
| --- | --- |
| `SPROUTBOAT_API_URL` | Control API URL. Overrides the saved endpoint. |
| `SPROUTBOAT_TOKEN` | API token. Overrides the saved credential. Set both to run without `login`. |
| `SPROUTBOAT_CONFIG_DIR` | Directory for `credentials.json`. Default `$XDG_CONFIG_HOME/sproutboat`, or `~/.config/sproutboat`. |
| `SPROUTBOAT_TOOLCHAIN_CACHE` | Compiler cache directory. Default `~/.cache/sproutboat`. |
| `SPROUTBOAT_ZIG` | Path to a Zig binary to use instead of downloading the pinned one. |
| `SPROUTBOAT_ZIG_URL` | Where to download the pinned Zig from. Its SHA-256 is still checked. |
| `SPROUTBOAT_UWS_TARBALL` | A uWebSockets source tarball to use instead of the bundled one. |
| `SPROUTBOAT_COMPILE_TIMEOUT_MS` | Porffor compile timeout. Default 600000. |
| `CC`, `CXX`, `AR` | C compiler, C++ compiler and archiver for host builds. Default `cc`, `c++` and `ar` when present, otherwise the bundled Zig. |
| `NO_COLOR` | Plain output. Output is also plain when stdout is not a terminal. |
| `SPROUTBOAT_NO_UPDATE_CHECK` | Skip the daily check for a newer release. Also skipped when `CI` is set. |

For the variables a running sprout reads, such as `PORT` and `SB_REQUEST_BODY_MAX`, see [Standalone binaries](/docs/get-started/standalone#configuration).