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 switch [slug]`	Saves the default team for this account and server
`link`	Interactively links this folder to an existing or new 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.

teams new, teams members, and teams add-member remain available; see teams --help.

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. Existing response shapes are retained, with 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.

Migration in 0.3.3

generate --generate NAME → add NAME; NAME:es256 → add NAME --alg es256.
init and directory switch → link.
projects → open for project administration.
check → whoami for context; provision detects and fills missing credentials. The old deep health-check/fix mode is no longer exposed.
ls and rm → list and remove; no command aliases.
teams switch now saves an account default; it does not modify folder links.
--scope and --no-env remain accepted for compatibility. Prefer --team and --export-env.
JSON keeps response fields but redacts credential values. Explicit exports provide the values.
usage and ledger stay separate: summary versus chronological charges.

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. This release is prepared as 0.3.5; publishing is a separate, explicit step.

Version 0.3.4 applies the artifact palette throughout command help, discovery, setup, resource lists and narrow layouts. Warp uses exact mint #8ed3b2, blue #93b7da and lilac #b9a7d2; Apple Terminal uses their fixed 256-color equivalents. Muted borders, headings and secondary text also use explicit palette colors. Basic terminals use neutral emphasis for command and resource accents. JSON, Markdown, NO_COLOR, --no-color, and ordinary pipes remain color-free.

Version 0.3.5 adds push, which sends the variables in .env.production, .env.local or .env to a linked Vercel project as sensitive values.