powerbase-cli 0.2.2

CLI for operating Powerbase console workflows

powerbase-cli

Python CLI for automating Powerbase console operations, with a command shape designed for Openclaw and other LLM agents.

What It Covers

powerbase-cli mirrors the main console workflows with a user-mode auth model:

• browser login bridge for CLI use
• local session persistence and refresh
• config and context management
• organizations, databases, instances, branches
• SQL execution
• publish diff and publish run
• sandbox file operations
• sandbox agent provider config, chat, and login workflows

The CLI is optimized for agent use:

• stable command groups
• --help explains parameter source and format
• --json is available for machine-readable output
• context can be saved so later commands need fewer flags

Database model:

• default path: powerbase instance create uses the managed Powerbase database flow
• advanced path: powerbase database create --dsn ... registers an existing external database connection for later use with --database-id
• powerbase database create does not provision a new physical database

Install And Run

Install from PyPI:

python3 -m pip install powerbase-cli
powerbase --help

From the repository root during development:

pip install -e .

Or run directly during development:

PYTHONPATH=src python3 -m powerbase_cli --help

Configuration Model

Values are resolved in this order:

1. command flags
2. environment variables
3. ~/.config/powerbase/
4. built-in defaults

Default local files:

~/.config/powerbase/
  config.toml
  auth.json
  context.json

Most users do not need environment variables.

Optional advanced overrides:

• POWERBASE_ACCESS_TOKEN and POWERBASE_REFRESH_TOKEN for non-browser or pre-issued login flows
• POWERBASE_INSTANCE_ID, POWERBASE_ORG_ID, and POWERBASE_BRANCH to prefill local context
• POWERBASE_CONFIG_DIR to isolate local state, for example in tests or E2E runs
• POWERBASE_OUTPUT to default to json

Authentication

Browser Login

The preferred flow is:

powerbase auth login
powerbase auth wait --login-id LOGIN_ID

The CLI now includes a built-in base_url and anon_key default for this deployment. The test package also bundles this environment's self-signed CA certificate, so most users can start with browser login directly and only use flags or environment variables when overriding that default.

The bundled CA is a test-only convenience for the current self-signed deployment. After the console moves to a publicly trusted TLS certificate, remove the bundled CA fallback and package resource, then keep only the built-in base_url and anon_key defaults.

This will:

1. request a CLI login session from Powerbase
2. return a login_id and browser URL
3. wait for the user to approve the request in their own browser
4. poll with powerbase auth wait --login-id ... until approval or until --timeout elapses (default 600 seconds, ten minutes)
5. save the resulting session to ~/.config/powerbase/auth.json

Use --timeout 0 on auth wait to wait without a time limit. Use a larger value if users need more than ten minutes to complete login. For agent-guided workflows, run powerbase auth login --json, return the login_url to the user, stop, and wait for the user to confirm browser approval before running powerbase auth wait --login-id ... --json. If the browser link expires or the user is not currently signed in to the console, rerun powerbase auth login --json to generate a fresh login URL before retrying.

Manual Token Import

Use this when browser login is not available in the current agent environment:

powerbase auth token-set \
  --access-token ACCESS_TOKEN \
  --refresh-token REFRESH_TOKEN \
  --expires-at 1760000000

The CLI is pinned to the production Powerbase console deployment and no longer exposes endpoint override flags.

Check Auth State

powerbase auth status --json

Refresh A Saved Session

powerbase auth refresh --json

Context Workflow

For repeated agent workflows, save the current org, instance, and branch:

powerbase context use-org ORG_ID
powerbase context use-instance INSTANCE_ID
powerbase context use-branch main
powerbase context show --json

After that, many commands can omit --instance-id.

Common Workflows

Discover Resources

powerbase org list --json
powerbase database list --json
powerbase instance list --json
powerbase branch list --instance-id INSTANCE_ID --json

Create An Instance With The Managed Database Flow

This is the default and recommended path:

powerbase org list --json
powerbase instance create --name todo-app --org-id ORG_ID --json

instance create returns when provisioning starts, not necessarily when every dependent resource is immediately readable. If instance get, branch list, or sandbox commands briefly say the instance is missing or partial, retry after a short wait.

Register And Reuse An External Database Connection

Use this only when you intentionally want the advanced bring-your-own-database flow:

powerbase database create --name todo-db --dsn "mysql://user:pass@host:3306/db" --db-type mysql --json
powerbase instance create --name todo-app --database-id DATABASE_ID --org-id ORG_ID --json

Notes for the advanced path:

• powerbase database create registers a DSN in Powerbase; it does not create a physical database server
• DSN credentials are sensitive and are stored by the platform
• branch and preview workflows may require SeekDB-compatible database behavior, not just generic MySQL wire compatibility
• deleting a Powerbase database record does not delete the external database itself

Switch To An Instance And Branch

powerbase context use-instance INSTANCE_ID
powerbase branch switch feature/demo --instance-id INSTANCE_ID --json
powerbase context use-branch feature/demo

When you create a branch with a name like feature/demo, later delete or SQL commands should prefer the normalized slug returned by the API, such as feature-demo, instead of assuming the original input string is still valid.

Run SQL

Inline SQL:

powerbase sql run --instance-id INSTANCE_ID --branch main --sql "SELECT 1" --json

From a file:

powerbase sql run --instance-id INSTANCE_ID --sql-file ./query.sql --json

Publish

powerbase publish diff --instance-id INSTANCE_ID --json
powerbase publish run --instance-id INSTANCE_ID --json

Sandbox Files

powerbase sandbox files tree --instance-id INSTANCE_ID --root / --json
powerbase sandbox files read --instance-id INSTANCE_ID /src/app.tsx --json
powerbase sandbox files upload --instance-id INSTANCE_ID ./local.txt --target-path /tmp --json

Sandbox Agent Providers

powerbase agent providers --instance-id INSTANCE_ID --json
powerbase agent status --instance-id INSTANCE_ID --provider cursor --json
powerbase agent login-url --instance-id INSTANCE_ID --provider cursor --json

Sandbox Agent Chat And Config

Powerbase provides a coding agent so users can build and evolve Powerbase-hosted apps through chat. powerbase agent chat is the default implementation interface for that workflow, while the rest of the CLI supports context, validation, and deployment around it. In the current product workflow, successful agent chat runs are also the normal path that produces previewable app changes.

Send one prompt to the sandbox agent and stream events as JSONL:

powerbase branch switch feature/demo --instance-id INSTANCE_ID --json

powerbase agent chat \
  --instance-id INSTANCE_ID \
  --provider cursor \
  --message "Build a todo app with create, complete, and delete actions." \
  --stream-jsonl

agent chat follows the sandbox's current branch for the automatic preview build. Use powerbase branch switch ... first when you want the generated preview to land on a feature branch. powerbase context use-branch ... only changes the local default value; it does not switch the remote sandbox by itself.

Treat powerbase sandbox files ..., powerbase sql run, and powerbase publish diff as inspection and validation tools around the Powerbase coding agent. Treat powerbase publish run as an explicit deployment action and do not run it unless the user asks to publish, deploy, release, or promote the result. Direct powerbase sandbox files create-file, upload, or delete operations can help inspect or adjust the remote project, but they do not by themselves trigger the preview build flow.

Read and update opencode provider config:

powerbase agent opencode-config get --instance-id INSTANCE_ID --json
powerbase agent opencode-config set --instance-id INSTANCE_ID --provider anthropic --api-key API_KEY --json
powerbase agent opencode-config delete --instance-id INSTANCE_ID --provider anthropic --json

Replace the sandbox opencode.json file:

powerbase agent opencode-json set --instance-id INSTANCE_ID --file ./opencode.json --json

Openclaw Usage Notes

When Openclaw or another LLM agent uses powerbase:

• prefer --json on all commands
• run discovery commands before write operations
• set context for long multi-step tasks
• treat powerbase agent chat as the default implementation interface for Powerbase-hosted apps
• treat successful powerbase agent chat runs as the normal path that produces previewable app changes
• use auth status before workflows that assume login
• use auth login --json to generate a login URL, then stop and hand login_url to the user
• do not have the agent open the browser login URL itself; the user must complete that approval step
• after the user confirms approval, run auth wait --login-id ... --json to complete login
• if a protected command says authentication is missing or expired, rerun auth login --json to generate a fresh login URL
• use sandbox files, sql run, and publish diff for inspection or validation around the Powerbase coding agent
• do not assume sandbox files write operations will trigger preview by themselves
• do not run publish run unless the user explicitly asks to publish, deploy, release, or promote the result
• remember that --json overrides a saved config output text setting for that command

Recommended agent sequence:

1. powerbase auth status --json
2. If unauthenticated, or if a protected command reports an auth error, run powerbase auth login --json and return the login_url plus login_id to the user
3. After the user confirms browser approval, run powerbase auth wait --login-id LOGIN_ID --json
4. powerbase context show --json
5. If no instance is selected, run powerbase instance list --json
6. If no suitable instance exists, prefer powerbase instance create --name ... --org-id ... --json
7. Use powerbase database ... only for the advanced bring-your-own-database path
8. Set context with powerbase context use-instance ...
9. If you want the sandbox agent preview on a non-main branch, run powerbase branch switch ...
10. Use powerbase agent chat ... as the primary implementation step for Powerbase-hosted app changes
11. Use sandbox files, sql, and publish diff to inspect or validate the result
12. Run publish run only when the user explicitly wants deployment or publication

Testing

Run the full CLI test suite:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m unittest discover -s tests -v

Compile the modules:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m py_compile src/powerbase_cli/*.py

Project Skill

A project skill for Cursor/Openclaw-style agent usage lives in:

./skills/powerbase-cli/SKILL.md

Design and auth review notes live in:

./docs/console-cli-plan.md