powerbase-cli 0.1.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:

python -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

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. print a browser URL
3. poll until browser approval or until --timeout elapses (default 600 seconds, ten minutes)
4. save the resulting session to ~/.config/powerbase/auth.json

Use --timeout 0 to wait without a time limit. Use a larger value if users need more than ten minutes to complete login. For agent-guided workflows, prefer powerbase auth login --no-wait --json so the CLI returns the login_url and exits immediately instead of blocking on polling. If the browser link expires or the user is not currently signed in to the console, rerun powerbase auth login --no-wait --json to generate a fresh login URL before retrying. If an agent or wrapper script is coordinating the workflow, it is still helpful to tell the user: after browser approval, return to the current session so the remaining steps can continue.

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

Use --base-url or --anon-key here only when you intentionally want to override the built-in deployment defaults.

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

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.

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
• use auth status before workflows that assume login
• prefer auth login --no-wait --json for browser login so the agent can hand login_url back to the user
• if a protected command says authentication is missing or expired, rerun auth login --no-wait --json to generate a fresh login URL
• do not have the agent open the browser login URL itself; the user must complete that approval step
• 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 --no-wait --json, return the login_url to the user, and wait for them to approve in the browser
3. powerbase context show --json
4. If no instance is selected, run powerbase instance list --json
5. If no suitable instance exists, prefer powerbase instance create --name ... --org-id ... --json
6. Use powerbase database ... only for the advanced bring-your-own-database path
7. Set context with powerbase context use-instance ...
8. If you want the sandbox agent preview on a non-main branch, run powerbase branch switch ...
9. Continue with branch, sql, publish, sandbox files, or agent commands

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:

./.cursor/skills/powerbase-cli-openclaw/SKILL.md

Design and auth review notes live in:

./docs/console-cli-plan.md