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.

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.3; publishing is a separate, explicit step.