powerbase-cli 0.1.0__py3-none-any.whl

powerbase_cli/commands/auth.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import argparse
+import time
+
+from .shared import AuthSession, AuthState, build_api, now_iso, render_output
+
+
+def handle_auth_login(args: argparse.Namespace) -> int:
+    store, config, _, _, api = build_api(args)
+    data = api.start_cli_login()
+    login_id = data["login_id"]
+    timeout_sec = int(args.login_timeout)
+    if timeout_sec < 0:
+        raise RuntimeError("--timeout must be >= 0 (0 means wait indefinitely).")
+    deadline: float | None = None
+    if timeout_sec > 0:
+        deadline = time.monotonic() + timeout_sec
+    print(f"Open this URL in your browser:\n{data['login_url']}\n")
+    if deadline is not None:
+        print(f"Waiting for authorization (timeout {timeout_sec}s)...")
+    else:
+        print("Waiting for authorization (no timeout)...")
+    while True:
+        polled = api.poll_cli_login(login_id)
+        status = polled.get("status")
+        if status == "pending":
+            if deadline is not None:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise RuntimeError(
+                        f"Login timed out after {timeout_sec} seconds without browser approval. "
+                        "Complete login sooner, run `powerbase auth login` again, or pass a larger "
+                        "`--timeout` (use `--timeout 0` to wait indefinitely)."
+                    )
+            else:
+                remaining = float("inf")
+
+            poll_sec = max(0.0, float(int(polled.get("poll_interval", 2))))
+            if poll_sec > 0:
+                sleep_sec = min(poll_sec, remaining)
+            elif deadline is not None:
+                # poll_interval 0 would spin; cap backoff when a deadline is set
+                sleep_sec = min(1.0, remaining)
+            else:
+                sleep_sec = 0.0
+
+            if sleep_sec > 0:
+                time.sleep(sleep_sec)
+            continue
+        if status == "approved":
+            auth = AuthState(
+                source="login",
+                base_url=config.base_url,
+                anon_key=config.anon_key,
+                session=AuthSession(**polled["session"]),
+                user=polled.get("user"),
+                updated_at=now_iso(),
+            )
+            store.save_auth(auth)
+            render_output(args, {"status": "approved", "saved_to": str(store.auth_path), "user": auth.user})
+            return 0
+        raise RuntimeError(f"Login failed with status: {status}")
+
+
+def handle_auth_status(args: argparse.Namespace) -> int:
+    store, _, _, session_manager, _ = build_api(args)
+    auth = session_manager.get_auth_state()
+    data = {
+        "authenticated": bool(auth),
+        "source": auth.source if auth else None,
+        "auth_file": str(store.auth_path),
+        "has_refresh_token": bool(auth and auth.session.refresh_token),
+        "seconds_until_expiry": session_manager.seconds_until_expiry(auth),
+        "user": auth.user if auth else None,
+    }
+    render_output(args, data)
+    return 0
+
+
+def handle_auth_refresh(args: argparse.Namespace) -> int:
+    _, _, _, session_manager, _ = build_api(args)
+    auth = session_manager.refresh()
+    render_output(args, {"status": "refreshed", "user": auth.user, "expires_at": auth.session.expires_at})
+    return 0
+
+
+def handle_auth_logout(args: argparse.Namespace) -> int:
+    store, _, _, _, _ = build_api(args)
+    store.clear_auth()
+    render_output(args, {"status": "logged_out", "auth_file": str(store.auth_path)})
+    return 0
+
+
+def handle_auth_token_set(args: argparse.Namespace) -> int:
+    store, config, _, _, _ = build_api(args)
+    auth = AuthState(
+        source="manual",
+        base_url=config.base_url,
+        anon_key=config.anon_key,
+        session=AuthSession(
+            access_token=args.access_token_value,
+            refresh_token=args.refresh_token_value,
+            expires_at=args.expires_at,
+        ),
+        updated_at=now_iso(),
+    )
+    store.save_auth(auth)
+    render_output(args, {"status": "saved", "auth_file": str(store.auth_path)})
+    return 0
+
+
+def register_auth_commands(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    auth = subparsers.add_parser(
+        "auth",
+        help="Manage login state.",
+        description="Log in, inspect, refresh, or clear the saved Powerbase session.",
+    )
+    auth_sub = auth.add_subparsers(dest="auth_command")
+    p = auth_sub.add_parser(
+        "login",
+        help="Start browser login.",
+        description=(
+            "Start browser-based login. This prints a login URL, polls until approval in the browser "
+            "or until --timeout seconds elapse (default 300), then saves the session to "
+            "~/.config/powerbase/auth.json. Use --timeout 0 to wait without a time limit."
+        ),
+    )
+    p.add_argument(
+        "--timeout",
+        dest="login_timeout",
+        type=int,
+        default=300,
+        metavar="SECONDS",
+        help=(
+            "Stop polling after this many seconds if login is not approved (default: 300). "
+            "Pass 0 to wait indefinitely."
+        ),
+    )
+    p.set_defaults(handler=handle_auth_login)
+    p = auth_sub.add_parser(
+        "status",
+        help="Show current auth status.",
+        description=(
+            "Show the active authentication source and whether refresh is available. "
+            "Reads env vars first, then ~/.config/powerbase/auth.json."
+        ),
+    )
+    p.set_defaults(handler=handle_auth_status)
+    p = auth_sub.add_parser(
+        "refresh",
+        help="Refresh the current session.",
+        description="Refresh the saved session using the refresh token from auth.json.",
+    )
+    p.set_defaults(handler=handle_auth_refresh)
+    p = auth_sub.add_parser("logout", help="Clear the saved auth session.", description="Delete the saved auth.json session.")
+    p.set_defaults(handler=handle_auth_logout)
+    p = auth_sub.add_parser(
+        "token-set",
+        help="Save tokens into auth.json.",
+        description=(
+            "Save an access token and optional refresh token into ~/.config/powerbase/auth.json. "
+            "If you skip the refresh token, the CLI cannot auto-refresh when the access token expires."
+        ),
+    )
+    p.add_argument("--access-token", dest="access_token_value", required=True, help="Access token to save.")
+    p.add_argument("--refresh-token", dest="refresh_token_value", help="Refresh token to save.")
+    p.add_argument("--expires-at", type=int, help="Unix timestamp when the access token expires.")
+    p.set_defaults(handler=handle_auth_token_set)

powerbase_cli/commands/branch.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import argparse
+
+from .shared import build_api, now_iso, render_output, require_instance, resolve_branch
+
+
+def handle_branch_list(args: argparse.Namespace) -> int:
+    _, _, context, _, api = build_api(args)
+    render_output(args, api.list_branches(require_instance(args.instance_id, context)))
+    return 0
+
+
+def handle_branch_create(args: argparse.Namespace) -> int:
+    store, _, context, _, api = build_api(args)
+    instance_id = require_instance(args.instance_id, context)
+    source_branch = args.source_branch or resolve_branch(None, context) or "main"
+    created = api.create_branch(instance_id, args.branch_name, source_branch)
+    branch_slug = created.get("branchSlug") or created.get("branch_slug") or args.branch_name
+    api.switch_branch(instance_id, branch_slug)
+    context.instance_id = instance_id
+    context.branch = branch_slug
+    context.updated_at = now_iso()
+    store.save_context(context)
+    render_output(args, {"created": created, "switched_to": branch_slug})
+    return 0
+
+
+def handle_branch_switch(args: argparse.Namespace) -> int:
+    store, _, context, _, api = build_api(args)
+    instance_id = require_instance(args.instance_id, context)
+    render_output(args, api.switch_branch(instance_id, args.branch_name))
+    context.instance_id = instance_id
+    context.branch = args.branch_name
+    context.updated_at = now_iso()
+    store.save_context(context)
+    return 0
+
+
+def handle_branch_delete(args: argparse.Namespace) -> int:
+    _, _, context, _, api = build_api(args)
+    instance_id = require_instance(args.instance_id, context)
+    render_output(args, api.delete_branch(instance_id, args.branch_name))
+    return 0
+
+
+def register_branch_commands(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    branch = subparsers.add_parser("branch", help="Branch commands.", description="Manage instance branches.")
+    branch_sub = branch.add_subparsers(dest="branch_command")
+    p = branch_sub.add_parser("list", help="List branches.", description="List branches for one instance.")
+    p.add_argument("--instance-id", help="Instance ID. Falls back to context.json.")
+    p.set_defaults(handler=handle_branch_list)
+    p = branch_sub.add_parser(
+        "create",
+        help="Create and switch a branch.",
+        description=(
+            "Create a branch through the platform API, then switch the sandbox to it. "
+            "If --source-branch is omitted, the saved context branch is used. The "
+            "returned `switched_to` value is the normalized branch slug; use that "
+            "slug for later commands such as `branch delete`."
+        ),
+    )
+    p.add_argument("branch_name", help="Branch slug to create.")
+    p.add_argument("--instance-id", help="Instance ID. Falls back to context.json.")
+    p.add_argument("--source-branch", help="Source branch slug. Example: main")
+    p.set_defaults(handler=handle_branch_create)
+    p = branch_sub.add_parser(
+        "switch",
+        help="Switch the sandbox branch.",
+        description="Switch the sandbox branch and update context.json.",
+    )
+    p.add_argument("branch_name", help="Branch slug to switch to.")
+    p.add_argument("--instance-id", help="Instance ID. Falls back to context.json.")
+    p.set_defaults(handler=handle_branch_switch)
+    p = branch_sub.add_parser(
+        "delete",
+        help="Delete a branch.",
+        description=(
+            "Delete a branch from the instance. Pass the normalized branch slug, not "
+            "necessarily the raw input you originally used with `branch create`. For "
+            "example, `feature/foo` may need to be deleted as `feature-foo`."
+        ),
+    )
+    p.add_argument("branch_name", help="Branch slug to delete.")
+    p.add_argument("--instance-id", help="Instance ID. Falls back to context.json.")
+    p.set_defaults(handler=handle_branch_delete)

powerbase_cli/commands/config_cmd.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import argparse
+
+from .shared import asdict, build_store, render_output, resolve_config
+
+
+def handle_config_list(args: argparse.Namespace) -> int:
+    store = build_store(args)
+    file_config = store.load_config()
+    effective = resolve_config(args, store)
+    render_output(
+        args,
+        {
+            "effective": asdict(effective),
+            "file": asdict(file_config),
+            "config_file": str(store.config_path),
+        },
+    )
+    return 0
+
+
+def handle_config_get(args: argparse.Namespace) -> int:
+    store = build_store(args)
+    effective = resolve_config(args, store)
+    value = getattr(effective, args.key.replace("-", "_"))
+    render_output(args, {args.key: value})
+    return 0
+
+
+def handle_config_set(args: argparse.Namespace) -> int:
+    store = build_store(args)
+    config = store.load_config()
+    setattr(config, args.key.replace("-", "_"), args.value)
+    store.save_config(config)
+    render_output(args, {"status": "saved", "config_file": str(store.config_path), args.key: args.value})
+    return 0
+
+
+def register_config_commands(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    config = subparsers.add_parser("config", help="Read or update config.", description="Manage config.toml values.")
+    config_sub = config.add_subparsers(dest="config_command")
+    p = config_sub.add_parser(
+        "list",
+        help="List effective config.",
+        description=(
+            "Show effective config and file-backed values. Remember that command-line "
+            "flags such as `--json` override values saved in config.toml."
+        ),
+    )
+    p.set_defaults(handler=handle_config_list)
+    p = config_sub.add_parser(
+        "get",
+        help="Get one config key.",
+        description=(
+            "Read one effective config key after applying flags, environment variables, "
+            "config.toml, and defaults. For example, passing `--json` still makes the "
+            "effective output value `json` even if config.toml says `text`."
+        ),
+    )
+    p.add_argument("key", choices=["base_url", "anon_key", "output"])
+    p.set_defaults(handler=handle_config_get)
+    p = config_sub.add_parser(
+        "set",
+        help="Set one config key.",
+        description=(
+            "Write one value into config.toml. Later commands can still override the "
+            "saved value with command-line flags such as `--json`."
+        ),
+    )
+    p.add_argument("key", choices=["base_url", "anon_key", "output"])
+    p.add_argument("value")
+    p.set_defaults(handler=handle_config_set)

powerbase_cli/commands/context.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import argparse
+
+from .shared import asdict, build_store, now_iso, render_output, resolve_context
+
+
+def handle_context_show(args: argparse.Namespace) -> int:
+    store = build_store(args)
+    file_context = store.load_context()
+    effective = resolve_context(store)
+    render_output(
+        args,
+        {"effective": asdict(effective), "file": asdict(file_context), "context_file": str(store.context_path)},
+    )
+    return 0
+
+
+def _save_context_update(
+    args: argparse.Namespace,
+    *,
+    instance_id: str | None = None,
+    org_id: str | None = None,
+    branch: str | None = None,
+) -> int:
+    store = build_store(args)
+    context = store.load_context()
+    if instance_id is not None:
+        context.instance_id = instance_id
+    if org_id is not None:
+        context.org_id = org_id
+    if branch is not None:
+        context.branch = branch
+    context.updated_at = now_iso()
+    store.save_context(context)
+    render_output(args, {"status": "saved", "context": asdict(context), "context_file": str(store.context_path)})
+    return 0
+
+
+def handle_context_clear(args: argparse.Namespace) -> int:
+    store = build_store(args)
+    context = store.clear_context(instance=args.instance, org=args.org, branch=args.branch)
+    render_output(args, {"status": "cleared", "context": asdict(context), "context_file": str(store.context_path)})
+    return 0
+
+
+def register_context_commands(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    context = subparsers.add_parser(
+        "context",
+        help="Manage default org, instance, and branch.",
+        description="Read or update ~/.config/powerbase/context.json for later commands.",
+    )
+    context_sub = context.add_subparsers(dest="context_command")
+    p = context_sub.add_parser("show", help="Show current context.", description="Show effective and saved context values.")
+    p.set_defaults(handler=handle_context_show)
+    p = context_sub.add_parser(
+        "use-instance",
+        help="Set the default instance.",
+        description=(
+            "Set the default instance used by later commands. The instance ID usually comes from "
+            "`powerbase instance list` or `powerbase context show`."
+        ),
+    )
+    p.add_argument("instance_id")
+    p.set_defaults(handler=lambda args: _save_context_update(args, instance_id=args.instance_id))
+    p = context_sub.add_parser("use-org", help="Set the default org.", description="Set the default organization ID.")
+    p.add_argument("org_id")
+    p.set_defaults(handler=lambda args: _save_context_update(args, org_id=args.org_id))
+    p = context_sub.add_parser(
+        "use-branch",
+        help="Set the default branch.",
+        description="Set the default branch slug, such as main or feature/my-change.",
+    )
+    p.add_argument("branch")
+    p.set_defaults(handler=lambda args: _save_context_update(args, branch=args.branch))
+    p = context_sub.add_parser(
+        "clear",
+        help="Clear saved context.",
+        description="Clear saved context values. If no flag is passed, all context values are cleared.",
+    )
+    p.add_argument("--instance", action="store_true", help="Clear only the saved instance_id.")
+    p.add_argument("--org", action="store_true", help="Clear only the saved org_id.")
+    p.add_argument("--branch", action="store_true", help="Clear only the saved branch.")
+    p.set_defaults(handler=handle_context_clear)

powerbase_cli/commands/database.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import argparse
+
+from .shared import build_api, render_output
+
+
+def handle_database_list(args: argparse.Namespace) -> int:
+    _, _, _, _, api = build_api(args)
+    render_output(args, api.list_databases())
+    return 0
+
+
+def handle_database_get(args: argparse.Namespace) -> int:
+    _, _, _, _, api = build_api(args)
+    render_output(args, api.get_database(args.database_id))
+    return 0
+
+
+def handle_database_create(args: argparse.Namespace) -> int:
+    _, _, _, _, api = build_api(args)
+    render_output(args, api.create_database(args.name, args.dsn, args.description, args.db_type))
+    return 0
+
+
+def handle_database_update(args: argparse.Namespace) -> int:
+    _, _, _, _, api = build_api(args)
+    render_output(
+        args,
+        api.update_database(args.database_id, args.name, args.dsn, args.description, args.db_type),
+    )
+    return 0
+
+
+def handle_database_delete(args: argparse.Namespace) -> int:
+    _, _, _, _, api = build_api(args)
+    render_output(args, api.delete_database(args.database_id))
+    return 0
+
+
+def register_database_commands(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    database = subparsers.add_parser(
+        "database",
+        help="Registered database connection commands.",
+        description=(
+            "Discover or manage reusable database connections used by instances. "
+            "This command group is the advanced bring-your-own-database path. "
+            "Use `powerbase instance create` without `--database-id` for the default "
+            "managed Powerbase database flow."
+        ),
+    )
+    database_sub = database.add_subparsers(dest="database_command")
+    p = database_sub.add_parser(
+        "list",
+        help="List registered database connections.",
+        description=(
+            "List registered database connections visible to the current user. "
+            "Use this before `powerbase instance create --database-id ...` when you "
+            "intentionally want the advanced bring-your-own-database flow."
+        ),
+    )
+    p.set_defaults(handler=handle_database_list)
+    p = database_sub.add_parser(
+        "get",
+        help="Get one registered database connection.",
+        description=(
+            "Show one registered database connection by ID. The database ID usually "
+            "comes from `powerbase database list`."
+        ),
+    )
+    p.add_argument("database_id", help="Database ID from `powerbase database list`.")
+    p.set_defaults(handler=handle_database_get)
+    p = database_sub.add_parser(
+        "create",
+        help="Register an existing database connection.",
+        description=(
+            "Register an existing database DSN for advanced bring-your-own-database "
+            "workflows. This does not provision a new physical database. Use the "
+            "returned ID with `powerbase instance create --database-id ...`. Prefer "
+            "plain `powerbase instance create` for the default managed Powerbase "
+            "database flow."
+        ),
+    )
+    p.add_argument("--name", required=True, help="Database display name.")
+    p.add_argument(
+        "--dsn",
+        required=True,
+        help=(
+            "Existing database DSN or connection string. Treat this as sensitive: "
+            "credentials are sent to and stored by the Powerbase platform."
+        ),
+    )
+    p.add_argument("--description", help="Optional description shown in the console.")
+    p.add_argument(
+        "--db-type",
+        help=(
+            "Optional database type, such as mysql. Advanced bring-your-own-database "
+            "flows may require SeekDB-compatible behavior for branch operations."
+        ),
+    )
+    p.set_defaults(handler=handle_database_create)
+    p = database_sub.add_parser(
+        "update",
+        help="Update one registered database connection.",
+        description=(
+            "Update one registered database connection by ID. Pass only the fields "
+            "you want to change."
+        ),
+    )
+    p.add_argument("database_id", help="Database ID from `powerbase database list`.")
+    p.add_argument("--name", help="Updated database display name.")
+    p.add_argument(
+        "--dsn",
+        help="Updated DSN or connection string for an existing external database.",
+    )
+    p.add_argument("--description", help="Updated description.")
+    p.add_argument("--db-type", help="Updated database type.")
+    p.set_defaults(handler=handle_database_update)
+    p = database_sub.add_parser(
+        "delete",
+        help="Delete one registered database connection.",
+        description=(
+            "Delete one registered database connection by ID. This removes the "
+            "Powerbase-side record only; it does not delete the physical database. "
+            "Discover IDs with `powerbase database list` first."
+        ),
+    )
+    p.add_argument("database_id", help="Database ID from `powerbase database list`.")
+    p.set_defaults(handler=handle_database_delete)

powerbase_cli/commands/instance.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import argparse
+
+from .shared import build_api, render_output, require_instance
+
+
+def handle_instance_list(args: argparse.Namespace) -> int:
+    _, _, _, _, api = build_api(args)
+    render_output(args, api.list_instances())
+    return 0
+
+
+def handle_instance_get(args: argparse.Namespace) -> int:
+    _, _, context, _, api = build_api(args)
+    render_output(args, api.get_instance(require_instance(args.instance_id, context)))
+    return 0
+
+
+def handle_instance_create(args: argparse.Namespace) -> int:
+    _, _, _, _, api = build_api(args)
+    render_output(args, api.create_instance(args.name, args.database_id, args.org_id))
+    return 0
+
+
+def handle_instance_delete(args: argparse.Namespace) -> int:
+    _, _, context, _, api = build_api(args)
+    render_output(args, api.delete_instance(require_instance(args.instance_id, context)))
+    return 0
+
+
+def register_instance_commands(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    instance = subparsers.add_parser(
+        "instance",
+        help="Instance commands.",
+        description=(
+            "Read or change Powerbase instances. By default, `powerbase instance create` "
+            "uses the managed Powerbase database flow. Pass `--database-id` only when "
+            "you intentionally want the advanced bring-your-own-database path."
+        ),
+    )
+    instance_sub = instance.add_subparsers(dest="instance_command")
+    p = instance_sub.add_parser("list", help="List instances.", description="List instances visible to the current user.")
+    p.set_defaults(handler=handle_instance_list)
+    p = instance_sub.add_parser(
+        "get",
+        help="Get one instance.",
+        description="Show one instance. If --instance-id is omitted, the saved context instance_id is used.",
+    )
+    p.add_argument("--instance-id", help="Instance ID. Source: `powerbase instance list` or `powerbase context show`.")
+    p.set_defaults(handler=handle_instance_get)
+    p = instance_sub.add_parser(
+        "create",
+        help="Create an instance.",
+        description=(
+            "Create a new instance. Default behavior: if `--database-id` is omitted, "
+            "Powerbase creates or attaches the managed platform database for the "
+            "instance. Advanced behavior: pass `--database-id` to bind the instance "
+            "to an already registered external database connection. The create call "
+            "returns as soon as provisioning starts; `instance get`, `branch list`, "
+            "and sandbox operations may need a short retry window before the new "
+            "instance becomes fully readable."
+        ),
+    )
+    p.add_argument("--name", help="Optional instance name.")
+    p.add_argument(
+        "--database-id",
+        help=(
+            "Optional registered database ID for the advanced bring-your-own-database "
+            "flow. Omit this to use the default managed Powerbase database flow."
+        ),
+    )
+    p.add_argument("--org-id", help="Optional organization ID.")
+    p.set_defaults(handler=handle_instance_create)
+    p = instance_sub.add_parser(
+        "delete",
+        help="Delete an instance.",
+        description="Delete one instance. If --instance-id is omitted, the saved context instance_id is used.",
+    )
+    p.add_argument("--instance-id", help="Instance ID to delete.")
+    p.set_defaults(handler=handle_instance_delete)

powerbase_cli/commands/org.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import argparse
+
+from .shared import build_api, render_output
+
+
+def handle_org_list(args: argparse.Namespace) -> int:
+    _, _, _, _, api = build_api(args)
+    render_output(args, api.list_orgs())
+    return 0
+
+
+def register_org_commands(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    org = subparsers.add_parser("org", help="Organization commands.", description="Read Powerbase organizations.")
+    org_sub = org.add_subparsers(dest="org_command")
+    p = org_sub.add_parser("list", help="List organizations.", description="List organizations available to the current user.")
+    p.set_defaults(handler=handle_org_list)