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 against it

Add --json to any listing command for machine-readable output you can pipe into jq, scripts, or dashboards.

Commands

Command	What it does
`nearbase login`	Authenticate via your browser (device flow).
`nearbase logout`	Forget the stored credentials on this machine.
`nearbase ls`	List every database across your organizations. The default action.
`nearbase ls --json`	Emit the same listing as JSON.
`nearbase --help`	Show all commands and flags.
`nearbase --version`	Print the installed CLI version.

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.

Configuration

Variable	Default	Description
`NEARBASE_API_URL`	`https://console.nearbase.dev`	Override the API endpoint (used for staging or dev).

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

Configuration

Troubleshooting

Source

​Install

​Quick start

​Commands

​Example

​Authentication

​Configuration

​Troubleshooting

​Source

Install

Quick start

Commands

Example

Authentication

Configuration

Troubleshooting

Source