powerbase-cli 0.1.3__tar.gz → 0.1.5__tar.gz

{powerbase_cli-0.1.3 → powerbase_cli-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: powerbase-cli
-Version: 0.1.3
+Version: 0.1.5
 Summary: CLI for operating Powerbase console workflows
 Author: Powerbase
 Requires-Python: >=3.11
@@ -240,6 +240,8 @@ 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
@@ -257,6 +259,9 @@ powerbase agent chat \
 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
@@ -278,11 +283,16 @@ 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:
@@ -296,7 +306,9 @@ Recommended agent sequence:
 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. Continue with `branch`, `sql`, `publish`, `sandbox files`, or `agent` commands
+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
 
@@ -316,7 +328,7 @@ PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m py_compile src/powerbase_cli
 
 A project skill for Cursor/Openclaw-style agent usage lives in:
 
-`./.cursor/skills/powerbase-cli-openclaw/SKILL.md`
+`./skills/powerbase-cli/SKILL.md`
 
 Design and auth review notes live in:
 

{powerbase_cli-0.1.3 → powerbase_cli-0.1.5}/README.md

@@ -232,6 +232,8 @@ 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
@@ -249,6 +251,9 @@ powerbase agent chat \
 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
@@ -270,11 +275,16 @@ 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:
@@ -288,7 +298,9 @@ Recommended agent sequence:
 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. Continue with `branch`, `sql`, `publish`, `sandbox files`, or `agent` commands
+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
 
@@ -308,7 +320,7 @@ PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m py_compile src/powerbase_cli
 
 A project skill for Cursor/Openclaw-style agent usage lives in:
 
-`./.cursor/skills/powerbase-cli-openclaw/SKILL.md`
+`./skills/powerbase-cli/SKILL.md`
 
 Design and auth review notes live in:
 

{powerbase_cli-0.1.3 → powerbase_cli-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "powerbase-cli"
-version = "0.1.3"
+version = "0.1.5"
 description = "CLI for operating Powerbase console workflows"
 readme = "README.md"
 requires-python = ">=3.11"

{powerbase_cli-0.1.3 → powerbase_cli-0.1.5}/src/powerbase_cli/commands/agent.py

@@ -115,11 +115,14 @@ def register_agent_commands(subparsers: argparse._SubParsersAction[argparse.Argu
         "chat",
         help="Send a prompt to the sandbox agent.",
         description=(
-            "Send one prompt to the sandbox agent running in an instance. Use this when you want the sandbox "
-            "itself to inspect or modify the project. The automatic preview build follows the sandbox's current "
-            "branch, so run `powerbase branch switch` first when you want a feature-branch preview. By default "
-            "the command collects all streamed events and prints them as JSON. Use --stream-jsonl to print one "
-            "JSON event per line as events arrive."
+            "Send one prompt to the Powerbase coding agent running in an instance. This is the default "
+            "implementation interface when you want to build or evolve a Powerbase-hosted app through chat, "
+            "while the rest of the CLI handles context, validation, and deployment around that workflow. "
+            "In the current product workflow, successful runs here are also the normal path that produces "
+            "previewable app changes. "
+            "The automatic preview build follows the sandbox's current branch, so run `powerbase branch switch` "
+            "first when you want a feature-branch preview. By default the command collects all streamed events "
+            "and prints them as JSON. Use --stream-jsonl to print one JSON event per line as events arrive."
         ),
     )
     p.add_argument("--instance-id", help="Instance ID. Falls back to context.json.")

{powerbase_cli-0.1.3 → powerbase_cli-0.1.5}/src/powerbase_cli/commands/auth.py

@@ -75,8 +75,8 @@ def handle_auth_login(args: argparse.Namespace) -> int:
             "poll_interval": data.get("poll_interval", 2),
             "next_action": "ask_user_to_open_url",
             "message": (
-                "Give login_url to the user and stop here. "
-                "Do not poll yet. After the user confirms browser approval, run "
+                "Return login_url to the user and stop. "
+                "Do not open the URL or poll yet. After the user confirms approval, run "
                 f"`powerbase auth wait --login-id {login_id} --json`."
             ),
         },
@@ -149,9 +149,9 @@ def register_auth_commands(subparsers: argparse._SubParsersAction[argparse.Argum
         "login",
         help="Generate browser login URL.",
         description=(
-            "Start browser-based login and return a login URL plus login_id. "
-            "Give the login_url to the user, wait for them to confirm approval in their own browser, "
-            "then run `powerbase auth wait --login-id ...` to complete login."
+            "Start browser login and return login_url plus login_id. "
+            "Give the URL to the user. Do not open it or poll yet. "
+            "After the user confirms approval, run `powerbase auth wait --login-id ...`."
         ),
     )
     p.set_defaults(handler=handle_auth_login)

{powerbase_cli-0.1.3 → powerbase_cli-0.1.5}/src/powerbase_cli/commands/branch.py

@@ -67,7 +67,10 @@ def register_branch_commands(subparsers: argparse._SubParsersAction[argparse.Arg
     p = branch_sub.add_parser(
         "switch",
         help="Switch the sandbox branch.",
-        description="Switch the sandbox branch and update context.json.",
+        description=(
+            "Switch the remote sandbox branch and update context.json. Use this before `powerbase agent chat` "
+            "when you want the coding agent and preview build to target a specific branch."
+        ),
     )
     p.add_argument("branch_name", help="Branch slug to switch to.")
     p.add_argument("--instance-id", help="Instance ID. Falls back to context.json.")

{powerbase_cli-0.1.3 → powerbase_cli-0.1.5}/src/powerbase_cli/commands/context.py

@@ -69,7 +69,10 @@ def register_context_commands(subparsers: argparse._SubParsersAction[argparse.Ar
     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.",
+        description=(
+            "Set the default branch slug, such as main or feature/my-change. This updates only the local default "
+            "context value; it does not switch the remote sandbox branch used by previews or `powerbase agent chat`."
+        ),
     )
     p.add_argument("branch")
     p.set_defaults(handler=lambda args: _save_context_update(args, branch=args.branch))

{powerbase_cli-0.1.3 → powerbase_cli-0.1.5}/src/powerbase_cli/commands/parser.py

@@ -62,6 +62,9 @@ def build_parser() -> argparse.ArgumentParser:
         prog="powerbase",
         description=(
             "Operate Powerbase console workflows from the command line. "
+            "Powerbase supports agent-driven development for Powerbase-hosted apps, with "
+            "`powerbase agent chat` as the default implementation interface and the rest of the CLI "
+            "covering auth, context, resources, validation, and publish operations. "
             "Default instance creation uses the managed Powerbase database flow; "
             "`powerbase database ...` is the advanced bring-your-own-database path."
         ),

{powerbase_cli-0.1.3 → powerbase_cli-0.1.5}/src/powerbase_cli/commands/publish.py

@@ -25,9 +25,17 @@ def handle_publish_run(args: argparse.Namespace) -> int:
 
 
 def register_publish_commands(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
-    publish = subparsers.add_parser("publish", help="Publish commands.", description="Generate diffs and publish an instance.")
+    publish = subparsers.add_parser(
+        "publish",
+        help="Publish commands.",
+        description="Inspect publish diffs and publish an instance when the user explicitly wants deployment.",
+    )
     publish_sub = publish.add_subparsers(dest="publish_command")
-    p = publish_sub.add_parser("diff", help="Show publish diff.", description="Generate publish diff for the current instance.")
+    p = publish_sub.add_parser(
+        "diff",
+        help="Show publish diff.",
+        description="Generate publish diff for the current instance as an inspection step before deployment.",
+    )
     p.add_argument("--instance-id", help="Instance ID. Falls back to context.json.")
     p.add_argument("--target", default="prod", help="Publish target. Default: prod")
     p.set_defaults(handler=handle_publish_diff)
@@ -35,7 +43,9 @@ def register_publish_commands(subparsers: argparse._SubParsersAction[argparse.Ar
         "run",
         help="Run publish flow.",
         description=(
-            "Publish the current instance. If --sql is omitted, the command first runs publish diff and uses its SQL."
+            "Publish the current instance. Use this only when the user explicitly asks to publish, deploy, "
+            "release, or promote the result. If --sql is omitted, the command first runs publish diff and uses "
+            "its SQL."
         ),
     )
     p.add_argument("--instance-id", help="Instance ID. Falls back to context.json.")

{powerbase_cli-0.1.3 → powerbase_cli-0.1.5}/src/powerbase_cli/commands/sandbox.py

@@ -48,9 +48,27 @@ def handle_files_delete(args: argparse.Namespace) -> int:
 
 
 def register_sandbox_commands(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
-    sandbox = subparsers.add_parser("sandbox", help="Sandbox commands.", description="Read or modify sandbox files.")
+    sandbox = subparsers.add_parser(
+        "sandbox",
+        help="Sandbox commands.",
+        description=(
+            "Inspect or modify the remote sandbox filesystem for a Powerbase instance. Treat this as the "
+            "remote inspection and control surface around the Powerbase coding agent, not the default full-app "
+            "implementation interface. Direct file operations here do not by themselves trigger the preview "
+            "build flow."
+        ),
+    )
     sandbox_sub = sandbox.add_subparsers(dest="sandbox_command")
-    files = sandbox_sub.add_parser("files", help="Sandbox file commands.", description="Read or modify sandbox files.")
+    files = sandbox_sub.add_parser(
+        "files",
+        help="Sandbox file commands.",
+        description=(
+            "Read or modify files in the remote Powerbase sandbox. Use these commands for inspection, validation, "
+            "and targeted file operations around agent-driven development. Successful `powerbase agent chat` runs "
+            "are the normal path for previewable app changes; these file operations do not trigger preview by "
+            "themselves."
+        ),
+    )
     files_sub = files.add_subparsers(dest="files_command")
     p = files_sub.add_parser("list", help="List a directory.", description="List sandbox files at one path.")
     p.add_argument("--instance-id", help="Instance ID. Falls back to context.json.")

{powerbase_cli-0.1.3 → powerbase_cli-0.1.5}/src/powerbase_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: powerbase-cli
-Version: 0.1.3
+Version: 0.1.5
 Summary: CLI for operating Powerbase console workflows
 Author: Powerbase
 Requires-Python: >=3.11
@@ -240,6 +240,8 @@ 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
@@ -257,6 +259,9 @@ powerbase agent chat \
 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
@@ -278,11 +283,16 @@ 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:
@@ -296,7 +306,9 @@ Recommended agent sequence:
 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. Continue with `branch`, `sql`, `publish`, `sandbox files`, or `agent` commands
+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
 
@@ -316,7 +328,7 @@ PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m py_compile src/powerbase_cli
 
 A project skill for Cursor/Openclaw-style agent usage lives in:
 
-`./.cursor/skills/powerbase-cli-openclaw/SKILL.md`
+`./skills/powerbase-cli/SKILL.md`
 
 Design and auth review notes live in:
 

{powerbase_cli-0.1.3 → powerbase_cli-0.1.5}/tests/test_cli_help.py

@@ -19,6 +19,8 @@ class CliHelpTests(unittest.TestCase):
         self.assertIn("command flags", help_text)
         self.assertIn("environment", help_text)
         self.assertIn("Operate Powerbase console workflows", help_text)
+        self.assertIn("agent-driven development", help_text)
+        self.assertIn("default implementation interface", help_text)
         self.assertIn("--insecure", help_text)
         self.assertIn("--ca-cert", help_text)
 
@@ -28,6 +30,7 @@ class CliHelpTests(unittest.TestCase):
         login_parser = auth_parser._subparsers._group_actions[0].choices["login"]
         help_text = login_parser.format_help()
         self.assertIn("login_id", help_text)
+        self.assertIn("Do not open", help_text)
         self.assertIn("powerbase auth wait", help_text)
 
     def test_auth_wait_help_mentions_timeout(self) -> None:
@@ -69,10 +72,21 @@ class CliHelpTests(unittest.TestCase):
         agent_parser = parser._subparsers._group_actions[0].choices["agent"]
         chat_parser = agent_parser._subparsers._group_actions[0].choices["chat"]
         help_text = chat_parser.format_help()
-        self.assertIn("sandbox agent", help_text)
+        self.assertIn("Powerbase coding agent", help_text)
+        self.assertIn("default implementation interface", help_text)
+        self.assertIn("previewable app changes", help_text)
         self.assertIn("stream-jsonl", help_text)
         self.assertIn("feature-branch preview", help_text)
 
+    def test_sandbox_files_help_mentions_remote_control_surface(self) -> None:
+        parser = build_parser()
+        sandbox_parser = parser._subparsers._group_actions[0].choices["sandbox"]
+        files_parser = sandbox_parser._subparsers._group_actions[0].choices["files"]
+        help_text = files_parser.format_help()
+        self.assertIn("remote Powerbase sandbox", help_text)
+        self.assertIn("targeted file operations around agent-driven", help_text)
+        self.assertIn("do not trigger preview", help_text)
+
     def test_agent_help_does_not_expose_custom_provider_commands(self) -> None:
         parser = build_parser()
         agent_parser = parser._subparsers._group_actions[0].choices["agent"]
@@ -103,6 +117,30 @@ class CliHelpTests(unittest.TestCase):
         self.assertIn("--json", help_text)
         self.assertIn("config.toml says `text`", help_text)
 
+    def test_context_use_branch_help_mentions_remote_sandbox(self) -> None:
+        parser = build_parser()
+        context_parser = parser._subparsers._group_actions[0].choices["context"]
+        use_parser = context_parser._subparsers._group_actions[0].choices["use-branch"]
+        help_text = use_parser.format_help()
+        self.assertIn("does not switch the remote sandbox", help_text)
+        self.assertIn("powerbase agent chat", help_text)
+
+    def test_branch_switch_help_mentions_coding_agent(self) -> None:
+        parser = build_parser()
+        branch_parser = parser._subparsers._group_actions[0].choices["branch"]
+        switch_parser = branch_parser._subparsers._group_actions[0].choices["switch"]
+        help_text = switch_parser.format_help()
+        self.assertIn("coding agent", help_text)
+        self.assertIn("preview build", help_text)
+
+    def test_publish_run_help_mentions_explicit_user_request(self) -> None:
+        parser = build_parser()
+        publish_parser = parser._subparsers._group_actions[0].choices["publish"]
+        run_parser = publish_parser._subparsers._group_actions[0].choices["run"]
+        help_text = run_parser.format_help()
+        self.assertIn("user explicitly asks to", help_text)
+        self.assertIn("release", help_text)
+
     def test_normalize_global_argv_moves_root_flags_forward(self) -> None:
         normalized = normalize_global_argv(["auth", "status", "--json", "--config-dir", "/tmp/pb", "--insecure"])
         self.assertEqual(normalized, ["--json", "--config-dir", "/tmp/pb", "--insecure", "auth", "status"])