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

# CLI

> Manage your Nearbase Postgres instances from the terminal

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

## Install

```bash theme={null}
npm install -g @nearbase/cli
```

Requires Node.js ≥ 20. The package is published as [`@nearbase/cli`](https://www.npmjs.com/package/@nearbase/cli).

## Quick start

```bash theme={null}
nearbase login    # opens your browser to authenticate
nearbase          # list every database across all your orgs
```

<Steps>
  <Step title="Log in">
    `nearbase login` runs an OAuth-style device flow. The CLI prints a short
    code and opens [console.nearbase.dev](https://console.nearbase.dev) in your
    browser. Sign in and approve the displayed code — the CLI receives a
    long-lived token and stores it locally.
  </Step>

  <Step title="List your databases">
    `nearbase` (or `nearbase ls`) prints a table of every instance across every
    Clerk organization you belong to.
  </Step>

  <Step title="Script against it">
    Add `--json` to any listing command for machine-readable output you can pipe
    into `jq`, scripts, or dashboards.
  </Step>
</Steps>

## 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:

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

<Note>
  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.
</Note>

## 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](https://github.com/jiey2/nearbase-mono).