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.

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.