extraorbital

ExtraOrbital

Provision your infrastructure in one command.

ExtraOrbital detects the environment variables your code needs, provisions cloud resources, and writes credentials to your local .env. Existing values are preserved.

From your project folder

npx extraorbital
npx extraorbital provision --dry-run
npx extraorbital provision

On first use, choose a team once, then select an existing project or create a project with a lowercase, hyphenated slug. ExtraOrbital saves the folder's link in .extraorbital.json (safe to commit). Future commands use that link.

Detection reads example env files, empty or placeholder env variables, and exact environment-variable names in source. Only missing credentials are provisioned. Local secrets are generated automatically. Credential files are added to .gitignore.

A cloud dry run needs an existing identity to read the catalog; it never creates resources, attaches the folder, writes env files or generates keys. provision --local --dry-run previews local secrets entirely offline.

Or add resources manually

Command	What it does
catalog	Lists available cloud services
catalog mongo	Shows a service's env variables and settings
add mongo	Provisions a MongoDB resource and saves credentials
add redis --slug cache	Adds a named resource
add SESSION_SECRET	Generates a local 32-byte base64url secret
add JWT_PRIVATE_KEY --alg es256	Generates a local signing keypair
provision --local	Generates detected local secrets without an account or network

Prefix commands with npx extraorbital. Service-specific options come from the live catalog. Repeating the same service and slug in a project reuses the existing resource.

Secret names use uppercase environment-variable syntax. Supported keypair algorithms: es256, rs256, ed25519, vapid. Random secrets accept --bytes and --encoding (base64url, base64url-padded, base64, hex). Existing values are never rotated by default. --replace only replaces the explicitly named secrets inside ExtraOrbital's managed block. Local secrets are never uploaded.

Track resources and spending

Command	What it does
list	Lists provisioned resources
usage	Shows this month's cost, resource breakdown, completed months and monthly average
ledger	Shows recent nonzero charges, newest first

Inside a linked folder, these commands use its project. Outside one, they show the selected team's projects. Add --all for every project in the selected team, or --project <slug> to inspect an existing project without changing the folder link. Project-restricted credentials remain restricted by the server.

Costs are USD before credits; unavailable usage is not counted as zero. Ledger defaults to 20 entries. Interactive terminals offer another page; automation can use --limit 100 --cursor <cursor>. JSON includes zero-cost entries, full references and the next cursor.

Account and project context

Command	What it does
whoami	Shows account, current team, linked project and credit context
teams	Lists teams
teams new <slug>	Creates a team
teams switch [slug]	Saves the default team for this account and server
teams members	Lists a team's members
teams add-member <email>	Adds an existing account to the team
link	Links this folder to an existing or new project: pick a team, accept the suggested name or choose a project
open	Opens the project's dashboard
remove <service/slug>	Removes a resource and its managed env entries
login	Connects the machine to your account
logout	Signs out or unlinks the machine

Switching the default team never transfers projects or changes existing folder links. --team <slug> overrides only this command. Use link --project <slug> --team <slug> to explicitly change a folder's link. Project transfers are managed separately.

Push variables to Vercel

vercel link                                         # once per folder
npx extraorbital push --to vercel --target production
npx extraorbital push --target production,preview
npx extraorbital push --dry-run                     # the plan, nothing sent

--to vercel and --target production are the defaults, and every run prints the full command with them filled in. push reads the first of .env.production, .env.local and .env that exists — one file, never merged. Variables with no value or a placeholder (changeme, your-key) are never pushed; at a terminal you are offered provision for them, written into that same file. The folder must be linked with vercel link (or VERCEL_PROJECT_ID/VERCEL_ORG_ID set), and the token is VERCEL_TOKEN or the login the Vercel CLI already holds.

Values go up as sensitive: encrypted at rest and unreadable afterwards. Vercel does not allow that in development, so only production and preview are accepted. A variable already on the project for the same target is replaced; the plan marks it ~ before anything is sent. --yes is required when nothing can answer, and never provisions. Redeploy afterwards — running deployments keep their old values.

Agents and automation

npx extraorbital add mongo --project my-app --team studio --non-interactive --yes
npx extraorbital provision --project auto --team studio --non-interactive --yes
npx extraorbital usage --project my-app --json
npx extraorbital ledger --all --limit 100 --json
npx extraorbital usage --markdown

An explicit project slug on add, provision or link creates or reuses the project and attaches it to the directory. --project auto explicitly opts into deriving the name from the repository or folder. Without a project or saved link, non-interactive writes fail with a runnable setup example.

Every command and help page accepts --json and --markdown. Both suppress prompts, browser opening and colors. JSON remains one object on stdout; progress uses stderr. JSON responses have credential values redacted. Use the explicit add <service> --export-env when you need raw cloud credentials on stdout; do not pipe that output to logs. Local secrets are only written to the env file. Export cannot be combined with JSON or Markdown.

Tables have continuous borders, muted colors, and responsive layouts: descriptions wrap where practical and narrow terminals use labeled records. Color detection supports Warp truecolor, macOS Terminal's 256 colors, conservative basic-color fallback, NO_COLOR, and --no-color. Piped output has no color by default.

Run npx extraorbital help <command> for focused help and --help --verbose for advanced options.

Choosing a server (production or v2)

The CLI talks to production, https://extraorbital.dev, unless told otherwise. To use the v2 broker and its resource lifecycle:

export EXTRAORBITAL_SERVER_URL=https://v2.extraorbital.dev
npx extraorbital whoami

The server comes from, in order: --server <url>, EXTRAORBITAL_SERVER_URL, EXTRAORBITAL_API_URL, the server pinned in the folder's .extraorbital.json, then the default. A folder linked on one server keeps working on that server only: when --server or the environment names a different one, every command refuses rather than sending that server's team and project ids to the other. Unset the variable, or run link to move the folder to the new server.

Sessions from login --human, machine identities and saved default teams are stored per server under ~/.extraorbital/, so signing in to v2 never signs you out of production. logout and login --logout only forget the current server's session. Links printed by the CLI, such as open, use the active server.

Resource lifecycle (v2 only)

Command	What it does
operations <service/slug>	Lists recent operations on a resource
operation <id> --follow	Streams an operation's progress until it finishes; the exit code is the operation's. One that waits for a sensitive resource's key asks for its password and sends the key on every request
cancel <operation>	Asks a running operation to stop
delete <service/slug>	Deletes a resource and reports every part that is deleted or remains
backup <service/slug>	Backs up a resource's data
backups <service/slug>	Lists a resource's backups, newest first, marking the encrypted ones and those not restorable (password reset)
restore <service/slug> --from <backup> [--to <slug>]	Restores a backup into a new resource. An encrypted backup or a sensitive resource asks for that resource's password, and the new resource is sensitive under the same password. Where the restore waits for the key (supabase: awaiting resource key), --follow sends it on every read until it is done; without --follow, run operation <id> --follow within 20 minutes, which asks for the password
restore <service/slug> --from <backup> --in-place	Replaces the resource's data with the backup, keeping its address and credentials (also --mode in-place). Asks you to type the slug (--yes skips it, and is required without a terminal). The current data is backed up first; --follow names that pre-restore backup and says how it ended, including a rolled-back restore (RESTORE_ROLLED_BACK, data as it was) or a failed rollback (RESTORE_ROLLBACK_FAILED, with the command that restores the pre-restore backup). A sensitive resource asks for its password
clone <service/slug> --to <slug>	Copies a resource under a new slug
freeze / unfreeze <service/slug>	Stops a resource answering, keeping its data and credentials, and lets it answer again. A frozen resource is never deleted by the Free plan's idle cleanup (it still counts against Free limits); one frozen because the team's plan lapsed is unfrozen by paying
credentials [list | create | rotate | reveal | revoke] <service/slug> [<credential>]	Lists a resource's credentials (no secrets); creates one (--label, --read), rotates one (default the primary, --grace 24h), prints one's secret, or revokes one. A credential is named by id, label or primary; secrets go to stdout as NAME=value; a sensitive resource asks for its password

These commands appear in help only on the v2 broker. Against production they exit 2 and say how to switch. backup, restore, clone, freeze, unfreeze and credentials start an operation only when the service declares that capability in the catalog; otherwise they say the action is planned and exit 0. For a v2 broker at another URL (localhost, a preview deployment), set EXTRAORBITAL_FEATURES=v2.

Sensitive resources (v2 only)

Command	What it does
run [service/slug...] -- <command> [args...]	Runs a program with the project's credentials (or the named resources') in its environment, writing nothing to disk; its exit code is passed on
protect <service/slug>	Makes a resource sensitive: its credentials open only with your password
unprotect <service/slug>	Makes a sensitive resource standard again (needs the password)
rekey <service/slug>	Changes a sensitive resource's password; the credentials stay the same
reset-key <service/slug>	For a lost password: rotates every credential, keeps the data, sets a new password. Every backup taken before becomes permanently unrestorable (it is encrypted with the lost password); asks you to type the slug, or --yes
backup-credential [status | enable | disable] <service/slug>	Says whether a sensitive resource has a backup credential, turns one on (asks for the password and a confirmation, --yes skips the confirmation), or revokes it (no password needed)

The password never leaves the machine. The CLI derives a key from it with Argon2id (64 MiB, 3 passes, salted per resource) and sends only that key, in the X-EO-Resource-Key header. It is read from the terminal with echo off, or from a pipe with --password-stdin (one line; rekey reads the current password, then the new one), never from arguments or environment variables. New passwords are asked twice and need at least 12 characters.

A sensitive resource's credentials are meant for run. add and provision refuse to write them to .env unless given --write-env, and reset-key writes the new ones only with --write-env; --export-env prints them instead. A lost password cannot be recovered: reset-key replaces every credential, after which .env copies, host environment variables and CI secrets holding the old ones must be updated.

Scheduled backups skip a sensitive resource, because they would need its password. backup-credential enable trades that away for one resource: with a backup credential, ExtraOrbital can take encrypted backups of this resource without your password. Restoring any backup of a protected resource still needs the password. backup-credential disable, unprotect and deleting the resource revoke it. Without a terminal, enable needs --yes (and --password-stdin for the password).

A sensitive resource's backups are encrypted to a key that only its password opens: backup asks for the password unless the backup credential is on, restore always asks for it, and unfreeze of a parked sensitive resource asks too. rekey keeps old backups restorable under the new password; reset-key makes them unrestorable for good; unprotect makes them restorable without a password.

Changes

0.4.3. version prints the CLI version and the server it talks to.

0.4.2. restore --in-place (or --mode in-place) restores a backup into the resource itself, where the service declares it: typed confirmation of the slug (--yes without a terminal), the pre-restore backup named when it starts, and with --follow the outcome: succeeded (with the command that puts the replaced data back), rolled back, or rollback failed (with the pre-restore backup to restore). operation <id> --follow reports an in-place restore the same way. A sensitive resource asks for its password. Decision D3: backup-credential enable|disable|status lets ExtraOrbital back up a sensitive resource without its password; backups lists a resource's backups, marking the encrypted ones and those a reset-key made unrestorable; restore of an encrypted backup asks for the password, protects the new resource with it and, with --follow, sends the key to a restore that waits for it (supabase); reset-key warns that earlier backups become unrestorable.

0.4.1. freeze and unfreeze handle parking (decision D5): on a service that cannot keep credentials while frozen (b2, vector, supabase on a paid organization) freeze warns that the resource is backed up and deleted upstream and comes back with new credentials; unfreeze --follow prints the new primary at the end (otherwise credentials reveal does). Both ask a sensitive resource's password when the broker needs it.

0.4.0 (breaking, v2 broker). GET /api/v1/resources/{service}/{slug}/credentials now lists credential records without secrets; values are read only with POST …/credentials/{id}/reveal (primary for the primary). run and credentials reveal use it. Earlier CLIs read values from the GET and find none there now: run starts the program with no variables from ExtraOrbital. Upgrade with npm install -g extraorbital@latest. Every request now carries x-extraorbital-cli: <version>, so the broker can refuse an outdated CLI clearly next time. freeze also keeps a resource out of the Free plan's idle cleanup.

Development and publishing

Node.js 20 or later is required.

pnpm install
pnpm typecheck
pnpm test
pnpm build
npm pack --dry-run
npm publish

The publish lifecycle runs typechecking, tests and a fresh build. Publishing requires an authorized npm account.