Metadata-Version: 2.4
Name: powerbase-cli
Version: 0.2.0
Summary: CLI for operating Powerbase console workflows
Author: Powerbase
Requires-Python: >=3.11
Description-Content-Type: text/markdown

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

```bash
python -m pip install --upgrade powerbase-cli==0.2.0
powerbase --help
```

Version `0.2.x` is the production-pinned release line and always targets `https://console.appbuild.chat`.

From the repository root during development:

```bash
pip install -e .
```

Or run directly during development:

```bash
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:

```text
~/.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:

```bash
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:

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

```bash
powerbase auth status --json
```

### Refresh A Saved Session

```bash
powerbase auth refresh --json
```

## Context Workflow

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

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

```bash
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:

```bash
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:

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

```bash
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:

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

From a file:

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

### Publish

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

### Sandbox Files

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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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

Compile the modules:

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