OctaBase CLI

Command-line interface for managing self-hosted OctaBase projects (multi-tenant Supabase manager).

Install

npm i -g @octa-base/cli

Or, while developing locally from this repo:

cd octabase-cli
npm install
npm run build
npm link        # makes `octabase` globally available

Quick start

# 1. Authenticate via browser (device-code OAuth)
octabase login

# 2. See your projects
octabase projects list

# 3. Link the current folder to a project
cd ~/my-app
octabase link my-client-app

# 4. Inspect status / live stats
octabase status
octabase stats

# 5. Push migrations + deploy functions + restart, all at once
octabase deploy

# 6. Open the project in the browser
octabase open            # app URL
octabase open --admin    # OctaBase admin UI
octabase open --studio   # Supabase Studio

How auth works

octabase login runs the device-code OAuth flow (RFC 8628):

1. CLI requests a short-lived user code from the manager.
2. Browser opens automatically on the OctaBase admin UI (/cli).
3. You sign in (if needed) and approve the code.
4. Manager issues a long-lived opaque CLI token (prefixed octa_, SHA-256 hashed at rest).
5. CLI saves { manager_url, admin_url, token, email } to ~/.octabase/config.json (mode 0600).

If you'd rather paste a token (CI / scripting), pass all required URLs as flags so the command stays fully non-interactive:

octabase login \
  --token <jwt> \
  --url https://api.your-domain.com \
  --admin-url https://app.your-domain.com

If you omit --admin-url, the CLI will prompt for it interactively (it's required so octabase open --admin knows where the admin UI lives).

You can revoke any active CLI token from the OctaBase admin UI under Settings → CLI tokens.

Project linking

octabase link <slug> writes ./.octabase/config.json:

{
  "project_id": "uuid",
  "slug": "my-client-app",
  "manager_url": "https://api.your-domain.com"
}

All subsequent commands (status, db push, secrets reveal, logs, functions deploy, deploy, open, config diff) read this file.

Commands

| Command | Description | |---|---| | octabase login | Authenticate via device-code OAuth (or --token <jwt>) | | octabase init [name] | Scaffold a new project folder (supabase/migrations + supabase/functions) | | octabase projects list | List all projects (--format table\|json\|csv\|tsv) | | octabase link <slug> | Link current folder to a project | | octabase status | Show project status, URL, containers (--format, --json) | | octabase stats | Live CPU/RAM stream over WebSocket | | octabase start / stop / restart | Control the linked project's containers | | octabase secrets reveal | Decrypt service_role + secret_key (audit-logged) | | octabase logs <service> | Tail container logs (kong, db, auth, storage, …) — --tail <n> | | octabase db push / pull | supabase db against the linked project | | octabase functions deploy <name> | supabase functions deploy against the linked project | | octabase config diff | Compare local supabase/ folder vs. the linked project (drift report) | | octabase deploy | Full pipeline: migrations → functions → restart → health check | | octabase open | Open the project in the browser (default app URL) | | octabase upgrade | Check npm registry and upgrade to the latest version | | octabase completion <bash\|zsh> | Print shell completion script |

db and functions commands require the Supabase CLI installed locally — OctaBase CLI just injects the right --db-url / API URL.

octabase deploy — full release pipeline

octabase deploy
# 1. Push migrations         (skipped if no .sql in supabase/migrations)
# 2. Deploy each function    (every dir under supabase/functions/, except _shared / main / _*)
# 3. Restart containers      (stop → 1.5s → start)
# 4. Health check            (poll until all containers running, max 60s)

Skip individual steps:

octabase deploy --skip-db --skip-functions
octabase deploy --skip-restart --skip-health

Fails fast on the first error and prints a summary table at the end.

octabase open — open the project in the browser

octabase open                # app URL          (https://my-app.your-domain.com)
octabase open --studio       # Supabase Studio  (<app-url>/project/default)
octabase open --admin        # OctaBase admin   (<admin_url>/projects/<id>)
octabase open --logs         # OctaBase admin → logs tab
octabase open --print        # print URL to stdout instead of launching a browser

--admin and --logs use the admin_url saved during octabase login. If it's missing, the CLI tries to derive it from manager_url (replacing api. with app.) and warns you.

octabase config diff — local vs. remote

Lists migrations and functions that exist locally but not on the project (and vice versa), so you know what octabase deploy will push.

octabase config diff           # human-friendly
octabase config diff --json    # machine-readable

Exits with code 1 when drift is detected (useful in CI gates).

Shell completion

# bash
octabase completion bash | sudo tee /etc/bash_completion.d/octabase

# zsh (add to a directory in $fpath)
octabase completion zsh > "${fpath[1]}/_octabase"

Config files

| Path | Scope | Contents | |---|---|---| | ~/.octabase/config.json | Global (per-machine) | manager_url, admin_url, token, email | | ./.octabase/config.json | Per-project (in repo) | project_id, slug, manager_url |

Both are written with mode 0600. Safe to commit the project file; never commit the global one.

Roadmap

• [x] Device-code OAuth login
• [x] octabase deploy (full pipeline)
• [x] octabase open (app / studio / admin / logs)
• [x] octabase config diff
• [ ] octabase logs --follow
• [ ] octabase db reset with confirmation
• [ ] octabase secrets set for per-project env vars
• [ ] Standalone Postgres password reveal endpoint (currently prompted)
• [ ] octabase backup / restore (pg_dump wrapper)

License

MIT