powerbase-cli 0.1.0__tar.gz

powerbase_cli-0.1.0/PKG-INFO

@@ -0,0 +1,318 @@
+Metadata-Version: 2.4
+Name: powerbase-cli
+Version: 0.1.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 powerbase-cli
+powerbase --help
+```
+
+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
+```
+
+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 **300** seconds, five 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 five minutes to complete login.
+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:
+
+```bash
+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
+
+```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
+
+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.
+
+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
+- use `auth status` before workflows that assume login
+- use `auth token-set` if browser login is not practical in the current environment
+- remember that `--json` overrides a saved `config output text` setting for that command
+
+Recommended agent sequence:
+
+1. `powerbase auth status --json`
+2. If unauthenticated, run `powerbase auth login` or `powerbase auth token-set`
+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:
+
+```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:
+
+`./.cursor/skills/powerbase-cli-openclaw/SKILL.md`
+
+Design and auth review notes live in:
+
+`./docs/console-cli-plan.md`

powerbase_cli-0.1.0/README.md

@@ -0,0 +1,310 @@
+# 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 powerbase-cli
+powerbase --help
+```
+
+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
+```
+
+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 **300** seconds, five 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 five minutes to complete login.
+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:
+
+```bash
+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
+
+```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
+
+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.
+
+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
+- use `auth status` before workflows that assume login
+- use `auth token-set` if browser login is not practical in the current environment
+- remember that `--json` overrides a saved `config output text` setting for that command
+
+Recommended agent sequence:
+
+1. `powerbase auth status --json`
+2. If unauthenticated, run `powerbase auth login` or `powerbase auth token-set`
+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:
+
+```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:
+
+`./.cursor/skills/powerbase-cli-openclaw/SKILL.md`
+
+Design and auth review notes live in:
+
+`./docs/console-cli-plan.md`

powerbase_cli-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "powerbase-cli"
+version = "0.1.0"
+description = "CLI for operating Powerbase console workflows"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Powerbase" }]
+dependencies = []
+
+[project.scripts]
+powerbase = "powerbase_cli.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.package-data]
+powerbase_cli = ["certs/*.pem"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

powerbase_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

powerbase_cli-0.1.0/src/powerbase_cli/__init__.py

@@ -0,0 +1,5 @@
+"""Powerbase CLI package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

powerbase_cli-0.1.0/src/powerbase_cli/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())