Repository navigation
v0.54.0
Built on @sproutboat/runtime 0.44.0, @sproutboat/wire 0.22.4 and @sproutboat/toolchain 0.24.2 (runtime and wire from 0.43.0 and 0.22.3). Runtime 0.44.0 adds service bindings between Cloud apps from compatibility date 2026-11-18; every app is recompiled on its next build, since the runtime prelude changed. The Cloud-only features below need a Cloud control plane with sproutboat-cloud#42, #45 and #49; remote D1 and R2 also need a host whose agent serves the data routes (sproutd#93).
Added
-
Profiles:
--profile <name>andSPROUTBOAT_PROFILE. A profile is an endpoint, its stored credential and a default team, so one machine can hold a Community login and a Cloud login side by side and say which one a command uses.login --profile <name>makes one (it fixes the endpoint, so--api-urlmust match when the profile exists),logoutandwhoamiact on the profile in use,profile listshows them andprofile use <name>changes the default.whoamianddeploynow start with two lines,profileandendpoint, so a deploy never goes somewhere unannounced. A profile and an endpoint that name different places (--profile cloud --api-url <community>, or the same pair in the environment) are an error. Precedence:--api-urland--profile, thenSPROUTBOAT_API_URLandSPROUTBOAT_PROFILE, then the default profile, thenhttps://dash.sproutboat.com;--profilebeatsSPROUTBOAT_API_URLand--api-urlbeatsSPROUTBOAT_PROFILE. -
Global flags with Wrangler's meanings, accepted before or after the command:
-c, --config <file>(the project's config file; its directory is the project),--cwd <dir>,-e, --env <name>,--env-file <file>(repeat it; later files override earlier ones) and-v, --version.devandrunstill take--envand--env-fileas before, now through the same parser, and--flag=valueworks. A flag a command cannot honour is refused (deploy --env stagingexits 2 instead of deploying), a repeated single-value flag takes its last value, and everything after--is left alone. -
r2 object get | put | delete <bucket>/<key>, with Wrangler's flags.gettakes--file <path>or--pipe(bytes to stdout) and, with neither, writes./<key>like Wrangler;puttakes--fileor--pipeplus--content-type,--content-disposition,--content-encoding,--content-language,--cache-control(short forms--ct --cd --ce --cl --cc) and--expires, and uses the file's type when no content type is given;deleteis idempotent. On a Cloud endpoint<bucket>is a binding fromr2_bucketsand the objects live in the app's bucket on its host, 64 MiB each. A key follows the Cloud's rules (1 to 1024 bytes of UTF-8, no control character, no backslash, no empty,.or..segment) and a bad one is refused with the reason before anything is sent. A download is an inert attachment (application/octet-stream,nosniff,CSP: sandbox), so the object's own type is read fromx-object-content-type(only when it was stored) and shown in the note; a PUT always declares its length.data:read(get) anddata:write(put, delete) are the grants: a key without one is told which, and how to get it (the "Deploy and data" or "Read data" key preset). A rate limit and a busy host say when to retry; a backup capture, a full quota (507) and a failed audit each have their own message; a 502 or 503 from a Cloud host that does not serve R2 yet says "remote D1/R2 isn't available on this Cloud host yet".--profile,-cand--cwdwork as everywhere, and an unknown option is refused. Unlike Wrangler there is no local mode yet (--localis refused with the reason, and remote is the default), since dev keeps R2 objects in its broker store. On self-hosted Communitygetreads through the existing route by bucket name, andputanddeletereport that they are not supported yet. Follows sproutboat-cloud#49 (docs/host-data.md); real data needs a host agent that serves the R2 routes. -
deployments list | status | tail <id>.listshows the 10 most recent deployments of the project in this directory, newest first, with the live one marked;statusshows what is live and whether a host applied it; both take--json. On a Cloud endpoint a deployment is a build (GET /v1/apps/<app>/builds):tail <id>follows it server-side, from its first log line to its end state, so a deploy that was detached with Ctrl-C can be picked up again; it exits 1 when the build failed or was cancelled, and Ctrl-C only stops following (exit 130, the build keeps running). On self-hosted Community a deployment is a version,listandstatusread/api/projects/<app>/deployments, andtailsays there is nothing to follow. Needs sproutboat-cloud#49 for the build list. -
secretissecrets, andsecrets bulk [file]takes Wrangler's bulk file.secret bulkreads JSON{"NAME": "value", "OLD": null}(a null deletes) or a.envfile (no deletes), from the file or stdin, at most 100 entries, and refuses a bad name or value by name before sending anything. On a Cloud endpoint it is onePATCH /v1/apps/<app>/secrets, so one new version.secrets put,deleteandbulknow wait for a host to apply that version, aswrangler secret putdeploys at once (the Cloud already re-ships the same module with the new sealed secrets as a new record generation);--no-deployreturns as soon as the change is stored, which is what they did before. A host that fails to apply it is an error with the host's reason. Self-hosted Community still applies secrets on the next deploy or restart of the app (it has no redeploy route), so--no-deploychanges nothing there andbulkis one call per name. -
d1 executeandd1 migrations create | list | apply, with Wrangler's semantics.d1 execute <database> --command <sql> | --file <path>runs every statement of the script in order, in one transaction, against the local dev database (.sproutboat/dev/d1/<BINDING>.sqlite) unless--remoteis given, as Wrangler does; it prints JSON ([{ results, success, meta }]) when--jsonis passed or stdout is not a terminal.<database>is a binding fromd1_databases.--persist-to <dir>moves the local state,--yesskips the remote--fileconfirmation. Migrations aremigrations/NNNN_<name>.sql(the top-levelmigrations_dirinsproutboat.jsoncchanges the folder;createstarts at 0001 and goes one past the highest), applied in order, each in one transaction with its row in thed1_migrationstable (id,name,applied_at, Wrangler's schema); the first failing migration is rolled back, the earlier ones stay applied, and the command exits 1. A terminal asks before applying; CI does not.--remoteneeds a Sproutboat Cloud endpoint and itsPOST /v1/apps/<app>/d1/<BINDING>/query(data:writeto change data,data:readto SELECT only; a key without the grant is told which one and how to get it). A busy host, a rate limit, a refused statement (refused), a SQL error (with its statement number), a paused backup capture, a memory limit and a full quota each get their own message; a 502 or 503 from a Cloud host that does not serve D1 yet says "remote D1/R2 isn't available on this Cloud host yet". On self-hosted Community it says it is not supported yet. Follows sproutboat-cloud#49 (docs/host-data.md);--profile,-cand--cwdwork as everywhere. -
loginon a Sproutboat Cloud endpoint is the device-code flow (RFC 8628). It prints a code and a link, opens the browser when it can, and stores an account API key (CLI on <hostname>, Developer at most) for the team you approve.logoutrevokes that key on the server and then forgets it;whoamishows the team, the key and its access, and exits 1 when not logged in.--account <team>preselects a team. -
deployto the Cloud builds from source. It bundles the project, uploads the generated source by sha256 (skipped when the Cloud has it), asks the Cloud to build it, streams the build log (|per line), then prints✓ Built in 4.1 s · peak memory 742 MB (cap 1200 MB)and waits for a host to apply the generation the build wrote. Assets go up by hash first. A dropped log stream resumes from the last line and then falls back to polling; Ctrl-C cancels the build (exit 130);--no-waitreturns once the build is accepted and prints/v1/builds/<id>;--dry-runsays it would build in the Cloud. A queued build the builder is holding back shows why (for examplewaiting for memory (1172 MB available, a build needs 1600 MB)) and keeps waiting. A failed build prints its reason, its peak memory when known, and exits 1; a Cloud with builds off or no builder says so, and a 429 shows the Cloud's message. Then it printshttps://<app>.<team>.sproutboat.app.--module app.soand--sproutdwith--generationstay as operator paths; a team key's module upload is refused with "modules are built by the Cloud; run `sproutboat deploy` without --module". Logged out in a terminal it logs in first; with no terminal it fails namingSPROUTBOAT_API_TOKEN. Other bindings and crons insproutboat.jsoncare not sent yet and the deploy warns. -
SPROUTBOAT_API_TOKENalways wins over a stored login (SPROUTBOAT_TOKENstays as the older name).SPROUTBOAT_ACCOUNTand anaccountfield insproutboat.jsoncchoose the team, like Wrangler'saccount_id. Several teams can be stored per endpoint. -
The deploy target is the endpoint you are logged in to. The CLI asks it what it is (
GET /v1/config) and deploys the Cloud way or the Community way. There is no--cloudflag, since Wrangler also has one target chosen by credentials. -
secrets put,listanddeletework on a Sproutboat Cloud app, by name through/v1/apps/<app>/secrets, independent of deploys likewrangler secret. An app that is not deployed says to deploy first or pass--secrets-fileon the first deploy; a 403 namessecret:writeorsecret:list.secretstakes--api-urland--account. -
deploy --secrets-file <file>(Cloud) reads a.dev.varsor.envfile and merges its values into the app's secrets. A build deploy never puts them in the build spec (stored in plaintext): once the build is ready they are set withPATCH /v1/apps/<app>/secretsand the deploy waits for that newer generation, so on a first deploy the app is briefly live before its secrets land; it cannot be combined with--no-wait. A module deploy sendssecrets_patch.setin its PUT. A deploy never replaces or wipes the app's secrets, and never reads.dev.varsby itself. -
deployto the Cloud sends service bindings. Eachservicesentry is resolved to the same team's Cloud app of that name (GET /v1/apps) and sent as aservicebinding plus aservicesid map. A callee that is not deployed, a binding to the app itself, or acompatibility_datebefore 2026-11-18 fails before anything is uploaded, with the fix named.examples/kitchen-sinkis on 2026-11-18. Depends on the Cloud secrets contract and on service binding support in sproutd.
Changed
- The docs link in
--helpnow points to https://sproutboat.com/docs (docs.sproutboat.com redirects there). build --standaloneskips LTO unless you pass--release(or setSPROUTBOAT_RELEASE=1). Units still compile at-O3; only the link changes. Cold builds are faster and the link takes about 90 MB instead of 1.1 to 1.6 GB, at some request throughput: see docs/standalone.md, "Dev and release builds", for the measured numbers.--releaseis the old-flto -O3build, so publish binaries with it. Release and non-release binaries have separate build-cache entries.deployand non-standalone builds are unchanged.- The default endpoint is
https://dash.sproutboat.com(it washttps://dashboard.sproutboat.com). - Credentials live in
~/Library/Preferences/sproutboaton macOS, Wrangler's choice. The old~/.config/sproutboat/credentials.jsonis still read, and the next login writes the new place. Elsewhere nothing moves. sproutboat --helpis shorter and plainer. The tagline no longer says "on your own VPS", so it fits the Cloud and a self-hosted server alike. Each command has one short line (the detail is insproutboat <command> --help), internal terms like "native-fetch sprout", "broker" and "id-less storage bindings" are gone,deleteis under SHIP, andkvsays it covers keys, bulk data and exports. Every command has its own emoji (runis 🏃,rollbackis ⏪), and the ones that drew one cell wide now carry U+FE0F so the columns line up. A GLOBAL FLAGS section lists-h, --helpand-v, --version, and the footer points to--helpfor a command's options.- Profiles live in a new
profiles.json;credentials.jsondoes not change.sproutboat initpins the CLI in each project, so one machine often runs several versions, and every older CLI keeps readingcredentials.jsonexactly as before (version 1:activeApiUrlplus one credential per endpoint URL).profiles.jsonnext to it holds the profile names, the default profile and each profile's endpoint, and refers to the credential incredentials.jsoninstead of copying it. Only a second profile on an endpoint that already has one carries its own credential inprofiles.json;credentials.jsonthen holds the credential of the profile most recently saved or switched to (login,profile use) on that endpoint. Nothing to do when you upgrade: the endpoint you were logged in to becomes thedefaultprofile and every other stored endpoint a profile named after its host (dash.sproutboat.com,localhost-8787). Reading changes nothing on disk; the first login, logout orprofile usewritesprofiles.json. If you ran a pre-release build that wrote a version 2credentials.json, it is converted back on first use (andcredentials.v1.json, if present, can be deleted).
Fixed
- A command never ignores a flag it does not know, and a URL is never a project directory. In 0.53.1,
sproutboat deploy --api-url https://dash.sproutboat.comread the URL as the project directory, and--api-url=https://…was ignored, so the deploy went to the saved endpoint (a stored Community login, say) instead of the one named. Now every command checks its options before it runs: an unknown one stops it with exit 2 (unknown option --dry-runn (did you mean --dry-run?)),--flag=valueworks for every flag that takes a value, and a positional that looks likehttps://…is refused where a project directory or a name goes, with a pointer to--api-url,--profileandSPROUTBOAT_API_URL.--api-url <url>and--api-url=<url>now work ondeployand on every command that talks to a control plane (login,logout,whoami,secrets,versions,rollback,tail,domains,delete, the storage commands); the commands that talk to none (init,check,types,dev,run,build,toolchain,profile,complete) refuse it and say to use--profileorSPROUTBOAT_API_URL. Before this,versions,rollback,tail,domains,deleteand the storage commands had no--api-urlat all and went to the saved endpoint. init's help text andSURFACE.mdnow say it adds thedev,deployandcheckscripts, not justdevanddeploy. Wording only.