Deploy and rotate
Get your project's variables to production with push, see what reads them with remote, and replace secrets with rotate.
Three commands cover everything after provision:
| Command | Job |
|---|---|
push [target] | Send the variables to where the app runs |
remote | See and remove what reads them |
rotate | Replace secrets, and put the new ones where they are used |
Every destination gets credentials of its own, so revoking or rotating one never breaks your laptop, your teammates or another environment.
Deploy to Vercel
Link the folder with vercel link once, then:
npx extraorbital push vercel --dry-run # see what would be sent
npx extraorbital push vercel # production
npx extraorbital push vercel --environment production,previewYou'll see each variable marked + (new) or ~ (replaces the value on Vercel), then one line per resource with the credential minted for it. Redeploy for the values to take effect. They are sent as sensitive and cannot be read back from Vercel.
Let the app read them keylessly instead
Nothing stored on the platform, and every credential handed out expires within the hour:
npx extraorbital push vercel --keyless # proven at once with your Vercel login
npx extraorbital push github --keyless # prints a CI job to run onceIn the app, read the variables with fromOIDC():
import { fromOIDC } from "@extraorbital/neon/oidc"
const db = await fromOIDC()In GitHub Actions or GitLab CI, npx extraorbital run --oidc -- npm test runs a command with them. Keyless access has the details, including Google Cloud.
Any other host
Netlify, Railway, Cloudflare Workers, Render, a VPS: write the variables to a file only you can read, then copy them into the host's settings:
npx extraorbital push ./prod.env # written 0600, with credentials minted for this file
npx extraorbital push # a temporary file; its path is printedDelete the file once you've copied what you need. Its credentials stay valid until you revoke them with remote remove, or replace them by pushing to the same file again.
See and remove what reads your variables
npx extraorbital remoteNAME KIND READS LAST
acme/web Vercel · keyless every resource used Nov 10
vercel:acme-web:production Vercel · pushed neon/db, redis/c… pushed Nov 9 from ada-laptop
file:ada-laptop:tmp File · pushed neon/db pushed Nov 8 from ada-laptopnpx extraorbital remote remove vercel:acme-web:preview # revoke what was pushed to preview
npx extraorbital remote remove acme/web # take an app's keyless access awayRemoving revokes at once, so whatever runs with those credentials stops working. Values pushed to a host stay there until you delete them or push again.
Rotate after a leak
Rotate on the machine whose .env may have leaked, in the project's folder:
npx extraorbital rotate --dry-run # what would change
npx extraorbital rotate # every resource in .env, this machine's credentials
npx extraorbital rotate neon/db --grace 24h # one resource; the old secret works 24h morerotate replaces this machine's own credential on each resource and rewrites its block in .env, printing only the variable names. Credentials other machines and destinations hold are untouched. A resource where this machine reads the shared primary is skipped and named: rotate <resource> rotates it, for every machine that shares it.
Rotate production
npx extraorbital rotate remote vercel # production
npx extraorbital rotate remote vercel:acme-web:preview # preview, by its remote name
npx extraorbital rotate remote acme/web # a keyless app: what it holds is revokedrotate remote mints new credentials for the destination and pushes them there at once; the previous ones stop after 24 hours, or after --grace. A keyless app needs nothing pushed: its credentials are revoked, and it fetches new ones on its next request.
Rotate everything
After a leak you can't pin down, or when someone leaves the team, an admin or owner replaces every credential of the project in one go, from the folder linked to it:
npx extraorbital rotate --all --dry-run # what would change, nothing changed
npx extraorbital rotate --all --grace 24h # every machine, production, keyless apps✓ Rotated 8 credentials of web, revoked 1, 1 pushed credential retiring
neon/db · machine ada-laptop · rotated
neon/db · machine bob-desktop · rotated
neon/db · shared primary · rotated
neon/db · keyless acme/web · revoked
…
✓ Pushed new credentials to vercel:acme-web:production
Other machines put their new secrets in .env by themselves, on their next extraorbital commandEvery machine's own credential and the shared primary are rotated. Each machine gets the new secret in its .env on its next command, and yours gets it at once. Keyless apps have what they hold revoked and fetch new credentials on their next request. The Vercel project the folder is linked to is pushed to again. Any other destination keeps its old credential for the grace (24 hours by default) and is named, with the command to push to it before then. A sensitive resource is skipped and named: rotate <resource> rotates it with its password.
A member who runs rotate --all is refused. Members rotate their own machines' credentials with rotate.
What other machines see after a rotation
When someone else rotates a credential a machine reads (an admin's rotate --all, the dashboard, another folder of yours), that machine needs nothing done by hand. The next extraorbital command it runs in the project's folder notices that the secret in .env no longer matches and rewrites the block:
↻ neon/db was rotated elsewhere: its new secret is in .env nowIt checks at most every ten minutes per folder. A sensitive resource's secret takes its password, so .env is left alone and the line says so: extraorbital run <resource> -- <command> uses the new secret. Set EXTRAORBITAL_NO_ENV_REFRESH=1 to turn the check off.