Start here

Quickstart

Create services and save their credentials in your project. Requires Node.js 20 or later.

Provision what you need

Declare supported variables in .env.example or reference them in your code. Then run:

Terminal

npx extraorbital provision .

The CLI creates the matching services and fills missing values. Existing working values are preserved.

Preview the plan without creating resources or writing project files:

Terminal

npx extraorbital provision . --dry-run

A first run may register the machine, including during a dry run.

Use it

Load the environment file in your app, install the service’s SDK, and connect. For Redis:

Terminal

npm install @upstash/redis

cache.ts

import { Redis } from "@upstash/redis";

const redis = Redis.fromEnv();
await redis.set("status", "ready");

Keep credentials out of browser code and Git. The CLI adds the environment file to .gitignore; it cannot remove credentials already committed to history.

What you can provision

Browse all resources for setup, SDK examples, and service-specific limits.

Free allowances are shared across your account and apply only on the Free plan; paid plans are charged from the first unit. Unlinked machines can spend up to $5 each before you link them and are limited by the Free tier limits; usage is billed to your account after linking. Prototype resources unused for 30 days are deleted after a warning one week before expiry. R2 and B2 also have file-retention limits, even when the bucket is active.

Postgres storage consumes credit while idle. Stripe uses a shared test account. Read each guide before using it. See pricing for plans and rates.

When a human is needed

When provisioning reaches an allowance or requires account approval, the CLI prints a link and exits with code 3. Open the link to see the required action.

A machine may need to be linked to a person. A project may need to move to a paid team, upgrade its plan, or restore credit. Follow the action shown; do not repeatedly retry the command.

Moving a project preserves its resource credentials. Existing resource access follows each service’s credit and retention rules; it is not guaranteed to continue after credit runs out.

Run npx extraorbital login to link the machine before it reaches a limit. This is separate from paying for a team.

Accounts and projects

Machine: the CLI registers a local keypair and a stable label. EXTRAORBITAL_MACHINE can override the label.
Project: .extraorbital.json records the team and project for this folder. This file contains IDs, not credentials, and can be committed.
Name: the CLI can use the repository or folder name. Duplicate names receive a suffix.
Account: login links the machine to a person. An explicit EXTRAORBITAL_TOKEN takes precedence over cached credentials.

To select a team and project:

Terminal

npx extraorbital link --team acme --project web
npx extraorbital provision .

A conflicting --team or --project returns an error. Run link again to change the folder’s target. Linking a folder does not move existing resources.

Use --slug for another instance of a service:

Terminal

npx extraorbital add redis --slug sessions

How services are detected

The CLI matches exact variable names from the catalog, in this order:

Names in .env.example, .env.sample, or .env.template.
Empty or placeholder values in .env or .env.local.
Variable names referenced in source code.

It skips variables with real values, dependencies, build output, and lockfiles. Each detected service uses the name default.

Supported local secrets, such as JWT_SECRET, are generated locally. They do not create a hosted resource.

Automation

Run without prompts and inspect the exit code:

Terminal

npx extraorbital provision . --non-interactive --yes

Use --json for structured output. For CI, supply EXTRAORBITAL_TOKEN if you need an existing account’s access.

Terminal

npx extraorbital whoami
npx extraorbital list

These show the active identity and project resources. See CLI exit codes for failure handling.

← Previous

Add services to your app.

Resources