Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nearbase.dev/llms.txt

Use this file to discover all available pages before exploring further.

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
1

Log in

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.
2

List your databases

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

Script against it

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

​
Commands

CommandWhat it does
nearbase loginAuthenticate via your browser (device flow).
nearbase logoutForget the stored credentials on this machine.
nearbase lsList every database across your organizations. The default action.
nearbase ls --jsonEmit the same listing as JSON.
nearbase --helpShow all commands and flags.
nearbase --versionPrint 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:
  1. The CLI requests a one-time device_code and short user_code from the Nearbase API.
  2. Your browser opens to the console, where you sign in with Clerk and approve the displayed code.
  3. 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

VariableDefaultDescription
NEARBASE_API_URLhttps://nearbase.up.railway.appOverride 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.