CLI reference
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. 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. |
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 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. |
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 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. |
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.
Configure
| Command | Does |
|---|---|
domains <list | add <host> | verify <host> | delete <host>> [dir] |
Manage custom domains. See 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. |
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. |
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.