CLI

The Nearbase CLI lets you list and inspect your databases without leaving the terminal — think nvidia-smi, but for Postgres.

Install

npm install -g @nearbase/cli

Requires Node.js ≥ 20. The package is published as @nearbase/cli.

Quick start

nearbase login    # opens your browser to authenticate
nearbase          # list every database across all your orgs

nearbase login runs an OAuth-style device flow. The CLI prints a short code and opens console.nearbase.dev in your browser. Sign in and approve the displayed code — the CLI receives a long-lived token and stores it locally.

List your databases

nearbase (or nearbase ls) prints a table of every instance across every Clerk organization you belong to.

Script or use an AI agent

Add the global --json option for a stable machine-readable envelope. Use NEARBASE_TOKEN to inject a previously authorized token without writing it to disk.

Commands

nearbase login [--no-open]       Authenticate with the device flow
nearbase logout                  Forget locally stored credentials
nearbase ls [--org ORG]          List instances
nearbase get ID --org ORG        Get metadata without credentials
nearbase regions                 List available regions
nearbase engine-versions         List PostgreSQL versions
nearbase classes                 List offered instance classes
nearbase price                   Quote the current monthly price
nearbase create                  Dry-run or create a short-lived quote
nearbase create --confirm ID     Confirm a quote with an idempotency key

Run nearbase <command> --help for configuration flags. --org accepts an organization ID or slug. Write operations always require it explicitly.

Example

$ nearbase
┌───────────┬─────────────┬─────────┬──────────────────────┬─────────┐
│ Org       │ Name        │ Status  │ Region               │ Storage │
├───────────┼─────────────┼─────────┼──────────────────────┼─────────┤
│ acme      │ prod-main   │ running │ Tokyo (Japan)        │ 100 GB  │
│ acme      │ staging     │ running │ Tokyo (Japan)        │ 20 GB   │
│ side-proj │ playground  │ stopped │ Singapore (Singapore)│ 20 GB   │
└───────────┴─────────────┴─────────┴──────────────────────┴─────────┘
  3 instance(s)

Authentication

nearbase login uses an OAuth-style device flow:

The CLI requests a one-time device_code and short user_code from the Nearbase API.
Your browser opens to the console, where you sign in with Clerk and approve the displayed code.
The CLI exchanges the device code for a long-lived access token (90 days) and stores it on disk.

The token is written to ~/.config/nearbase/auth.json with file mode 0600 on Unix. To revoke access on a machine, run nearbase logout.

Tokens are scoped to your Clerk user and inherit the org memberships you have at the moment each request is made. Removing a user from an org takes effect on their next CLI command.

Agent and automation usage

Machine output uses one JSON document on stdout:

{"ok":true,"data":{"instances":[]}}

Failures use the same envelope on stderr with a stable error code and optional request ID. Exit codes are 0 for success, 1 for usage/general errors, 2 for authentication errors, and 3 for API, network, or timeout errors.

export NEARBASE_TOKEN='previously-authorized-token'
nearbase --json ls --org acme
nearbase --json price \
  --region cn-hangzhou \
  --engine-version 16 \
  --db-instance-class pg.n2.medium.1 \
  --db-instance-storage 20 \
  --db-instance-storage-type general_essd \
  --category Basic

For a remote login, nearbase --json login --no-open writes an authorization_required event containing the URL and user code to stderr, then waits for human approval.

Safe create flow

Creating an instance is intentionally two-step:

Run nearbase create with --org and all configuration flags. The command returns a ten-minute quote and does not charge or provision anything.
Confirm exactly that quote with nearbase create --confirm QUOTE_ID --idempotency-key STABLE_UNIQUE_KEY.
If credits cover the total, provisioning starts. Otherwise the command returns a Stripe Checkout URL that a person must open and complete.

The server revalidates org membership, SKU availability, price, and credits at confirmation. Reusing the same idempotency key replays the original result; using another key for the consumed quote is rejected. CLI JSON never includes database passwords or connection strings. Provider-backed dry runs are limited to five requests per user and organization per minute. Deletion, security-IP changes, payment-method management, start, stop, and restart are not exposed to agents.

Configuration

NEARBASE_API_URL defaults to https://console.nearbase.dev and may target staging or local development.
NEARBASE_TOKEN overrides the token file for CI and agent processes. Treat it as a secret and inject it through the runtime’s secret manager.

Troubleshooting

Not logged in. Run nearbase login first. — Run nearbase login.
Session expired or invalid. — Tokens are valid for 90 days; run nearbase login again.
Browser didn’t open. — Open the verification URL printed in the terminal manually.

Source

The CLI is open source. Issues, feature requests, and PRs are welcome at github.com/jiey2/nearbase-mono.

Getting Started

Instances

Billing

Install

Quick start

Commands

Example

Authentication

Agent and automation usage

Safe create flow

Configuration

Troubleshooting

Source

​Install

​Quick start

​Commands

​Example

​Authentication

​Agent and automation usage

​Safe create flow

​Configuration

​Troubleshooting

​Source

Install

Quick start

Commands

Example

Authentication

Agent and automation usage

Safe create flow

Configuration

Troubleshooting

Source