plato-sdk-v2 2.6.1__py3-none-any.whl → 2.7.0__py3-none-any.whl

plato/v1/cli/sandbox.py

@@ -25,12 +25,18 @@ from plato._generated.api.v1.gitea import (
     get_gitea_credentials,
     get_simulator_repository,
 )
-from plato._generated.api.v1.sandbox import setup_root_access, setup_sandbox, start_worker
+from plato._generated.api.v1.sandbox import start_worker
 from plato._generated.api.v2.jobs import get_flows as jobs_get_flows
 from plato._generated.api.v2.jobs import state as jobs_state
+from plato._generated.api.v2.sessions import (
+    add_ssh_key as sessions_add_ssh_key,
+)
 from plato._generated.api.v2.sessions import (
     close as sessions_close,
 )
+from plato._generated.api.v2.sessions import (
+    connect_network as sessions_connect_network,
+)
 from plato._generated.api.v2.sessions import (
     execute as sessions_execute,
 )
@@ -47,17 +53,19 @@ from plato._generated.api.v2.sessions import (
     state as sessions_state,
 )
 from plato._generated.models import (
-    AppSchemasBuildModelsSetupSandboxRequest,
+    AddSSHKeyRequest,
     AppSchemasBuildModelsSimConfigCompute,
     AppSchemasBuildModelsSimConfigDataset,
     AppSchemasBuildModelsSimConfigMetadata,
+    ConnectNetworkRequest,
     CreateCheckpointRequest,
     ExecuteCommandRequest,
     Flow,
-    SetupRootPasswordRequest,
     VMManagementRequest,
 )
-from plato.v1.cli.ssh import setup_ssh_for_sandbox
+from plato.v1.cli.proxy import ssh as gateway_ssh_command
+from plato.v1.cli.proxy import tunnel as gateway_tunnel_command
+from plato.v1.cli.ssh import generate_ssh_key_pair
 from plato.v1.cli.utils import (
     SANDBOX_FILE,
     console,
@@ -81,6 +89,10 @@ UUID_PATTERN = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-
 sandbox_app = typer.Typer(help="Manage sandboxes for simulator development")
 sandbox_app.add_typer(sandbox_verify_app, name="verify")
 
+# Register gateway SSH/tunnel commands
+sandbox_app.command(name="ssh")(gateway_ssh_command)
+sandbox_app.command(name="tunnel")(gateway_tunnel_command)
+
 
 def format_public_url_with_router_target(public_url: str | None, service_name: str | None) -> str | None:
     """Format public URL with _plato_router_target parameter for browser access.
@@ -130,41 +142,45 @@ def sandbox_start(
     # Common options
     timeout: int = typer.Option(1800, "--timeout", help="VM lifetime in seconds (default: 30 minutes)"),
     no_reset: bool = typer.Option(False, "--no-reset", help="Skip initial reset after ready"),
+    connect_network: bool = typer.Option(
+        True, "--network/--no-network", help="Connect VMs to WireGuard network for SSH access (default: enabled)"
+    ),
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
     working_dir: Path = typer.Option(
         None, "--working-dir", "-w", help="Working directory for .sandbox.yaml and .plato/"
     ),
 ):
-    """
-    Start a sandbox environment.
-
-    THREE MODES (pick one):
-
-    1. FROM CONFIG (-c): Use plato-config.yml in current directory
-
-        plato sandbox start -c
-        plato sandbox start -c -d base
-
-    2. FROM SIMULATOR/ARTIFACT (-s or -a): Start from existing artifact
-
-        -s <simulator>                      Latest tag
-        -s <simulator>:<tag>                Specific tag
-        -s <simulator>:<artifact-uuid>      Specific artifact (UUID detected)
-        -s <simulator> -a <artifact-uuid>   Explicit artifact
-        -a <artifact-uuid>                  Artifact only (no simulator name)
-
-    3. BLANK VM (-b): Create fresh VM with custom specs
-
-        plato sandbox start -b --service myapp
-        plato sandbox start -b --service myapp --cpus 4 --memory 2048
-
-    EXAMPLES:
-
-        plato sandbox start -c                                    # From config
-        plato sandbox start -s espocrm                            # Latest artifact
-        plato sandbox start -s espocrm:staging                    # Staging tag
-        plato sandbox start -s espocrm:e9c25ca5-1234-5678-...     # Specific artifact
-        plato sandbox start -a e9c25ca5-1234-5678-9abc-...        # Artifact only
+    """Start a sandbox environment for simulator development.
+
+    Creates a VM that can be used to develop and test simulators. You must pick exactly
+    one mode to specify how the sandbox should be created.
+
+    Mode Options (pick exactly one):
+        -c, --from-config: Create VM using settings from plato-config.yml in the current
+            directory. Uses the compute specs (cpus, memory, disk) from the config file.
+        -s, --simulator: Start from an existing simulator. Supports formats:
+            '-s name' (latest tag), '-s name:tag' (specific tag), '-s name:uuid' (specific artifact)
+        -a, --artifact-id: Start directly from a specific artifact UUID
+        -b, --blank: Create a blank VM with custom specs (requires --service)
+
+    Config Mode Options:
+        -d, --dataset: Which dataset from the config to use (default: "base")
+
+    Simulator Mode Options:
+        -t, --tag: Artifact tag to use (default: "latest")
+
+    Blank VM Options:
+        --service: Service name for the blank VM (required with -b)
+        --cpus: Number of CPUs (default: 2)
+        --memory: Memory in MB (default: 1024)
+        --disk: Disk size in MB (default: 10240)
+
+    Common Options:
+        --timeout: VM lifetime in seconds before auto-shutdown (default: 1800 = 30 min)
+        --no-reset: Skip the initial environment reset after the VM is ready
+        --no-network: Disable WireGuard network connection (enabled by default for SSH access)
+        -j, --json: Output results as JSON instead of formatted text
+        -w, --working-dir: Directory to store .sandbox.yaml and .plato/ files
     """
     api_key = require_api_key()
 
@@ -328,12 +344,17 @@ def sandbox_start(
     # Create session using v2 SDK
     if not json_output:
         console.print("[cyan]Creating sandbox...[/cyan]")
+        if connect_network:
+            console.print("[cyan]Network connection will be established after VM is ready...[/cyan]")
+            console.print(
+                "[yellow]Note: First connection on older VMs may take a few minutes to install WireGuard[/yellow]"
+            )
 
     try:
         plato = PlatoV2(api_key=api_key)
         if not env_config:
             raise ValueError("No environment configuration provided")
-        session = plato.sessions.create(envs=[env_config], timeout=timeout)
+        session = plato.sessions.create(envs=[env_config], timeout=timeout, connect_network=connect_network)
 
         # Get session info
         session_id = session.session_id
@@ -363,102 +384,64 @@ def sandbox_start(
             session.reset()
 
         # Setup SSH for ALL modes (so you can SSH into any sandbox)
-        ssh_host = None
-        ssh_config_path = None
         ssh_private_key_path = None
 
-        if job_id:
+        if session_id and connect_network:
             if not json_output:
                 console.print("[cyan]Setting up SSH access...[/cyan]")
             try:
-                # Step 1: Generate SSH key pair and create SSH config (like Go hub does)
-                # For config mode: use "plato" user (setup_sandbox configures this)
-                # For artifact/simulator modes: use "root" user (setup_root_access configures this)
-                ssh_username = "plato" if (mode == "config" and full_dataset_config_dict) else "root"
-
+                # Step 1: Generate SSH key pair
                 if not json_output:
                     console.print("[cyan]  Generating SSH key pair...[/cyan]")
 
-                base_url = os.getenv("PLATO_BASE_URL", "https://plato.so")
-                ssh_info = setup_ssh_for_sandbox(base_url, job_id, username=ssh_username, working_dir=working_dir)
-                ssh_host = ssh_info["ssh_host"]
-                ssh_config_path = ssh_info["config_path"]
-                ssh_private_key_path = ssh_info["private_key_path"]
-                ssh_public_key = ssh_info["public_key"]
+                public_key, private_key_path = generate_ssh_key_pair(session_id[:8], working_dir)
+                ssh_private_key_path = private_key_path
 
+                # Step 2: Add SSH key to all VMs in the session via API
                 if not json_output:
-                    console.print(f"[cyan]  SSH config: {ssh_config_path}[/cyan]")
+                    console.print("[cyan]  Adding SSH key to VMs...[/cyan]")
 
-                # Step 2: Upload SSH key to sandbox
-                # For --from-config mode: use setup_sandbox with full config
-                # For --simulator/--artifact-id modes: use setup_root_access (just SSH key, no config changes)
-                if not json_output:
-                    console.print("[cyan]  Uploading SSH key to sandbox...[/cyan]")
-
-                if mode == "config" and full_dataset_config_dict:
-                    # Full config from plato-config.yml - use setup_sandbox API
-                    compute_dict = full_dataset_config_dict.get("compute", {})
-                    metadata_dict = full_dataset_config_dict.get("metadata", {})
-                    services_dict = full_dataset_config_dict.get("services")
-                    listeners_dict = full_dataset_config_dict.get("listeners")
-
-                    compute_obj = AppSchemasBuildModelsSimConfigCompute(
-                        cpus=compute_dict.get("cpus", 2),
-                        memory=compute_dict.get("memory", 2048),
-                        disk=compute_dict.get("disk", 10240),
-                        app_port=compute_dict.get("app_port", 80),
-                        plato_messaging_port=compute_dict.get("plato_messaging_port", 7000),
-                    )
-
-                    metadata_obj = AppSchemasBuildModelsSimConfigMetadata(
-                        name=metadata_dict.get("name", sim_name or "sandbox"),
-                        description=metadata_dict.get("description", ""),
-                        source_code_url=metadata_dict.get("source_code_url"),
-                        start_url=metadata_dict.get("start_url", "blank"),
-                        license=metadata_dict.get("license"),
-                        variables=metadata_dict.get("variables"),
-                        flows_path=metadata_dict.get("flows_path"),
-                    )
+                ssh_username = "root"
+                add_key_request = AddSSHKeyRequest(
+                    public_key=public_key,
+                    username=ssh_username,
+                )
 
-                    dataset_config_obj = AppSchemasBuildModelsSimConfigDataset(
-                        compute=compute_obj,
-                        metadata=metadata_obj,
-                        services=services_dict,
-                        listeners=listeners_dict,
+                with get_http_client() as client:
+                    add_key_response = sessions_add_ssh_key.sync(
+                        client=client,
+                        session_id=session_id,
+                        body=add_key_request,
+                        x_api_key=api_key,
                     )
 
-                    dataset_value = dataset_name or state_extras.get("dataset", "base")
-                    setup_request = AppSchemasBuildModelsSetupSandboxRequest(
-                        service=sim_name or "",
-                        dataset=str(dataset_value) if dataset_value else "",
-                        plato_dataset_config=dataset_config_obj,
-                        ssh_public_key=ssh_public_key,
-                    )
+                if not json_output:
+                    # Debug: show full response
+                    console.print("[yellow]DEBUG add_ssh_key response:[/yellow]")
+                    console.print(f"  success: {add_key_response.success}")
+
+                    # Show results for each job
+                    for jid, result in add_key_response.results.items():
+                        console.print(f"  [cyan]Job {jid}:[/cyan]")
+                        console.print(f"    success: {result.success}")
+                        console.print(f"    error: {result.error}")
+                        console.print("    output:")
+                        if result.output:
+                            console.print(result.output)
+                        else:
+                            console.print("      (none)")
+                        if result.success:
+                            console.print(f"  [green]✓[/green] {jid}: SSH key added")
+                        else:
+                            console.print(f"  [red]✗[/red] {jid}: {result.error}")
 
-                    with get_http_client() as client:
-                        _setup_response = setup_sandbox.sync(
-                            client=client,
-                            public_id=job_id,
-                            body=setup_request,
-                            x_api_key=api_key,
-                        )
+                if add_key_response.success:
+                    if not json_output:
+                        console.print("[green]SSH setup complete![/green]")
+                        console.print("  [cyan]SSH:[/cyan] plato sandbox ssh")
                 else:
-                    # Artifact/simulator modes - use setup_root_access API (just SSH key, preserves existing config)
-                    setup_root_request = SetupRootPasswordRequest(
-                        ssh_public_key=ssh_public_key,
-                    )
-
-                    with get_http_client() as client:
-                        _setup_response = setup_root_access.sync(
-                            client=client,
-                            public_id=job_id,
-                            body=setup_root_request,
-                            x_api_key=api_key,
-                        )
-
-                if not json_output:
-                    console.print("[green]SSH setup complete![/green]")
-                    console.print(f"  [cyan]SSH:[/cyan] ssh -F {ssh_config_path} {ssh_host}")
+                    if not json_output:
+                        console.print("[red]SSH key setup failed - SSH may not work[/red]")
 
             except Exception as e:
                 if not json_output:
@@ -482,16 +465,15 @@ def sandbox_start(
             "created_at": datetime.now(timezone.utc).isoformat(),
             **state_extras,
         }
-        # Add SSH info if available from setup_sandbox
-        if ssh_host:
-            state["ssh_host"] = ssh_host
-        if ssh_config_path:
-            state["ssh_config_path"] = ssh_config_path
+        # Add SSH private key path if available
         if ssh_private_key_path:
             state["ssh_private_key_path"] = ssh_private_key_path
         # Add heartbeat PID
         if heartbeat_pid:
             state["heartbeat_pid"] = heartbeat_pid
+        # Add network connection status
+        if connect_network:
+            state["network_connected"] = True
         save_sandbox_state(state, working_dir)
 
         # Close the plato client (heartbeat process keeps session alive)
@@ -504,11 +486,9 @@ def sandbox_start(
                 "job_id": job_id,
                 "public_url": display_url,  # Full URL with _plato_router_target
             }
-            if ssh_host:
-                output["ssh_host"] = ssh_host
-            if ssh_config_path:
-                output["ssh_config_path"] = ssh_config_path
-                output["ssh_command"] = f"ssh -F {ssh_config_path} {ssh_host}"
+            if ssh_private_key_path:
+                output["ssh_private_key_path"] = ssh_private_key_path
+                output["ssh_command"] = "plato sandbox ssh"
             console.print(json.dumps(output))
         else:
             console.print("\n[green]Sandbox started successfully![/green]")
@@ -517,15 +497,36 @@ def sandbox_start(
             if public_url:
                 display_url = format_public_url_with_router_target(public_url, sim_name)
                 console.print(f"  [cyan]Public URL:[/cyan]  {display_url}")
-            if ssh_host and ssh_config_path:
-                console.print(f"  [cyan]SSH:[/cyan]         ssh -F {ssh_config_path} {ssh_host}")
+            if ssh_private_key_path:
+                console.print("  [cyan]SSH:[/cyan]         plato sandbox ssh")
+            # Warn if using host-only routing (no VM-to-VM mesh)
+            if connect_network and hasattr(session, "network_host_only") and session.network_host_only:
+                console.print("\n[yellow]Warning: WireGuard not available in VM - using host-only routing[/yellow]")
+                console.print("[yellow]  SSH from outside works, but VM-to-VM networking is disabled[/yellow]")
             console.print(f"\n[dim]State saved to {SANDBOX_FILE}[/dim]")
 
     except Exception as e:
         if json_output:
             console.print(json.dumps({"error": str(e)}))
         else:
-            console.print(f"[red]Failed to start sandbox: {e}[/red]")
+            error_msg = str(e)
+            # Check if it's a network connection error with VM details
+            if "Network connection failed" in error_msg or "WireGuard" in error_msg:
+                console.print("[red]Failed to start sandbox - network setup failed[/red]")
+                console.print("[yellow]VM error:[/yellow]")
+                # Clean up error message - remove SSH warnings and format nicely
+                clean_lines = []
+                for line in error_msg.split("\n"):
+                    line = line.strip()
+                    # Skip SSH warnings
+                    if line.startswith("Warning:") or "known hosts" in line:
+                        continue
+                    if line:
+                        clean_lines.append(line)
+                for line in clean_lines:
+                    console.print(f"  {line}")
+            else:
+                console.print(f"[red]Failed to start sandbox: {e}[/red]")
         raise typer.Exit(1) from e
 
 
@@ -542,30 +543,23 @@ def sandbox_snapshot(
     messaging_port: int = typer.Option(None, "--messaging-port", help="Override messaging port"),
     target: str = typer.Option(None, "--target", help="Override target domain (e.g., myapp.web.plato.so)"),
 ):
-    """
-    Create a snapshot of the current sandbox state.
-
-    Saves the artifact ID to .sandbox.yaml so it can be used by
-    'plato pm submit base' without needing to specify it manually.
-
-    CONFIG BEHAVIOR:
-
-        - Sandboxes started from config (-c): Automatically includes plato-config.yml,
-          flows.yml, app_port, and messaging_port in the snapshot.
-        - Sandboxes started from artifact: Inherits config from parent artifact.
-          Use --include-config to override with local config files.
-
-    USAGE:
-
-        plato sandbox snapshot           # Creates snapshot, saves artifact_id
-        plato sandbox snapshot --json    # JSON output
-        plato sandbox snapshot -c        # Force include local config files
-        plato sandbox snapshot --app-port 8080  # Override app port
-
-    NEXT STEPS:
-
-        After snapshot, you can submit for review:
-        plato pm submit base             # Reads artifact_id from .sandbox.yaml
+    """Create a snapshot of the current sandbox state.
+
+    Captures the current VM state as an artifact that can be submitted for review or
+    used as a starting point for future sandboxes. The artifact ID is saved to
+    .sandbox.yaml so it can be used by 'plato pm submit base'.
+
+    For sandboxes started from config (-c), automatically includes plato-config.yml and
+    flows.yml in the snapshot. For sandboxes started from an artifact, config is inherited
+    from the parent.
+
+    Options:
+        -j, --json: Output results as JSON instead of formatted text
+        -c, --include-config: Force including local plato-config.yml and flows.yml in the
+            snapshot. Auto-enabled for sandboxes started from config.
+        --app-port: Override the internal application port stored in the artifact
+        --messaging-port: Override the Plato messaging port stored in the artifact
+        --target: Override the target domain (e.g., myapp.web.plato.so)
     """
     api_key = require_api_key()
     state = require_sandbox_state()
@@ -660,26 +654,11 @@ def sandbox_snapshot(
 
 @sandbox_app.command(name="stop")
 def sandbox_stop():
-    """
-    Stop and destroy the current sandbox.
+    """Stop and destroy the current sandbox.
 
-    Closes the session, cleans up SSH keys, and removes .sandbox.yaml.
+    Terminates the remote VM session, stops the heartbeat background process,
+    cleans up local SSH keys created for this sandbox, and removes .sandbox.yaml.
     Run this when you're done with the sandbox or want to start fresh.
-
-    REQUIRES:
-
-        .sandbox.yaml in current directory (created by 'plato sandbox start')
-
-    USAGE:
-
-        plato sandbox stop
-
-    WHAT IT DOES:
-
-        1. Stops the heartbeat process
-        2. Closes the remote session
-        3. Removes SSH config and keys
-        4. Deletes .sandbox.yaml
     """
     api_key = require_api_key()
     state = require_sandbox_state()
@@ -703,16 +682,9 @@ def sandbox_stop():
                 x_api_key=api_key,
             )
 
-        # Clean up SSH config and key files (like Go hub does)
-        ssh_config_path = state.get("ssh_config_path")
+        # Clean up SSH key files
         ssh_private_key_path = state.get("ssh_private_key_path")
 
-        if ssh_config_path:
-            config_file = Path(ssh_config_path)
-            if config_file.exists():
-                config_file.unlink()
-                console.print(f"[dim]Removed {ssh_config_path}[/dim]")
-
         if ssh_private_key_path:
             private_key_file = Path(ssh_private_key_path)
             public_key_file = Path(ssh_private_key_path + ".pub")
@@ -731,32 +703,78 @@ def sandbox_stop():
         raise typer.Exit(1) from e
 
 
-@sandbox_app.command(name="status")
-def sandbox_status(
+@sandbox_app.command(name="connect-network")
+def sandbox_connect_network(
+    session_id: str = typer.Option(None, "--session", "-s", help="Session ID (uses .sandbox.yaml if not provided)"),
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ):
+    """Connect all jobs in a session to a WireGuard network.
+
+    Establishes encrypted peer-to-peer networking between VMs in the session,
+    allowing SSH access from outside and VM-to-VM communication. Pre-generates
+    WireGuard keys, allocates IPs from the session network subnet, and configures
+    full mesh networking.
+
+    Options:
+        -s, --session: Session ID to connect. If not provided, reads from .sandbox.yaml
+        -j, --json: Output results as JSON instead of formatted text
     """
-    Show current sandbox status and connection info.
+    api_key = require_api_key()
+
+    # Get session ID from argument or .sandbox.yaml
+    if session_id is None:
+        state = require_sandbox_state()
+        session_id = require_sandbox_field(state, "session_id")
+
+    console.print(f"[cyan]Connecting session {session_id} to network...[/cyan]")
+
+    try:
+        with get_http_client() as client:
+            result = sessions_connect_network.sync(
+                client=client,
+                session_id=session_id,
+                body=ConnectNetworkRequest(),
+                x_api_key=api_key,
+            )
 
-    Displays the public URL, SSH config, VM status, and other details
-    from .sandbox.yaml plus live status from the API.
+        if json_output:
+            console.print_json(data=result)
+        else:
+            # Display results
+            statuses = result.get("statuses", {})
+            success_count = sum(1 for s in statuses.values() if s.get("success"))
+            total_count = len(statuses)
 
-    REQUIRES:
+            if success_count == total_count:
+                console.print(f"[green]All {total_count} jobs connected to network[/green]")
+            else:
+                console.print(f"[yellow]{success_count}/{total_count} jobs connected[/yellow]")
+
+            for job_id, status in statuses.items():
+                if status.get("success"):
+                    wg_ip = status.get("wireguard_ip", "unknown")
+                    console.print(f"  [green]✓[/green] {job_id}: {wg_ip}")
+                else:
+                    error = status.get("error", "unknown error")
+                    console.print(f"  [red]✗[/red] {job_id}: {error}")
 
-        .sandbox.yaml in current directory (created by 'plato sandbox start')
+    except Exception as e:
+        console.print(f"[red]Failed to connect network: {e}[/red]")
+        raise typer.Exit(1) from e
 
-    USAGE:
 
-        plato sandbox status           # Human-readable output
-        plato sandbox status --json    # JSON output for scripts
+@sandbox_app.command(name="status")
+def sandbox_status(
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+):
+    """Show current sandbox status and connection info.
 
-    OUTPUT INCLUDES:
+    Displays information from .sandbox.yaml combined with live status from the API.
+    Shows session ID, job ID, VM status (running/stopped/etc.), public URL for browser
+    access, SSH connection details, network connection status, and heartbeat status.
 
-        - Public URL (for browser access)
-        - SSH config path (for 'ssh -F <config> sandbox-<id>')
-        - VM status (running/stopped/etc.)
-        - Session ID, Job ID
-        - Service name, dataset
+    Options:
+        -j, --json: Output all status info as JSON instead of formatted text
     """
     state = require_sandbox_state()
 
@@ -876,10 +894,14 @@ def sandbox_status(
             console.print(f"  [cyan]Created:[/cyan]     {state.get('created_at')}")
 
         # Display SSH command if available
-        ssh_host = state.get("ssh_host")
-        ssh_config_path = state.get("ssh_config_path")
-        if ssh_host and ssh_config_path:
-            console.print(f"  [cyan]SSH:[/cyan]         ssh -F {ssh_config_path} {ssh_host}")
+        ssh_private_key_path = state.get("ssh_private_key_path")
+        job_id = state.get("job_id")
+        if ssh_private_key_path and job_id:
+            console.print("  [cyan]SSH:[/cyan]         plato sandbox ssh")
+
+        # Display network connection status
+        if state.get("network_connected"):
+            console.print("  [cyan]Network:[/cyan]     [green]connected[/green] (WireGuard)")
 
         # Display heartbeat process status
         heartbeat_pid = state.get("heartbeat_pid")
@@ -930,38 +952,24 @@ def sandbox_start_worker(
     wait_timeout: int = typer.Option(240, "--wait-timeout", help="Timeout in seconds for --wait (default: 240)"),
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ):
-    """
-    Start the Plato worker in the sandbox.
-
-    The worker handles flow execution and state tracking. Only start it
-    AFTER verifying login works (via 'plato sandbox flow' or browser testing).
-
-    REQUIRES:
-
-        .sandbox.yaml in current directory (created by 'plato sandbox start')
-        plato-config.yml in current directory (or specify with --config-path)
-
-    USAGE:
-
-        plato sandbox start-worker                    # Uses plato-config.yml in cwd
-        plato sandbox start-worker --wait             # Wait for worker to be ready
-        plato sandbox start-worker -d base            # Specify dataset
-        plato sandbox start-worker --config-path ./plato-config.yml
-
-    WORKFLOW POSITION:
-
-        1. plato sandbox start -c
-        2. plato sandbox start-services
-        3. plato sandbox flow             ← verify login works first!
-        4. plato sandbox start-worker --wait  ← you are here (wait ~2-3 min)
-        5. plato sandbox flow             ← run login again to verify with worker
-        6. plato sandbox state --verify-no-mutations  ← verify no mutations
-        7. plato sandbox snapshot
-
-    WARNING:
-
-        Starting the worker with broken login causes infinite error loops.
-        Always verify login works before starting the worker.
+    """Start the Plato worker in the sandbox.
+
+    The worker is the Plato component that handles flow execution, database audit
+    tracking, and state management. It should be started AFTER verifying the login
+    flow works manually, since a broken login with an active worker causes error loops.
+
+    Reads the dataset configuration from plato-config.yml to configure the worker
+    with the correct services, listeners, and compute settings.
+
+    Options:
+        -s, --service: Service name to configure the worker for. Defaults to value in
+            .sandbox.yaml if not provided.
+        -d, --dataset: Dataset name from plato-config.yml (default: "base")
+        --config-path: Path to plato-config.yml. Defaults to current directory.
+        -w, --wait: After starting, poll the state API until the worker is ready.
+            Useful in scripts to ensure the worker is fully initialized.
+        --wait-timeout: Timeout in seconds for --wait (default: 240 seconds)
+        -j, --json: Output results as JSON instead of formatted text
     """
     api_key = require_api_key()
     state = require_sandbox_state()
@@ -1122,36 +1130,20 @@ def sandbox_sync(
     timeout: int = typer.Option(120, "--timeout", "-t", help="Command timeout in seconds"),
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ):
-    """
-    Sync local files to the sandbox VM.
-
-    Uploads local files to the remote sandbox. Useful for updating
-    docker-compose.yml, flows.yml, or other config without restarting.
-
-    REQUIRES:
-
-        .sandbox.yaml in current directory (created by 'plato sandbox start')
-
-    USAGE:
-
-        plato sandbox sync                    # Sync current directory
-        plato sandbox sync ./base             # Sync specific directory
-        plato sandbox sync -r /custom/path    # Custom remote path
-
-    DEFAULT REMOTE PATH:
-
-        /home/plato/worktree/<service>/
-
-    WHAT IT SYNCS:
+    """Sync local files to the sandbox VM.
 
-        - Respects .gitignore patterns
-        - Excludes .git, __pycache__, node_modules, etc.
-        - Creates tar archive and extracts on remote
+    Creates a tar archive of local files and uploads it to the remote VM via the
+    execute API. Excludes common build artifacts (.git, __pycache__, node_modules,
+    .venv, etc.) to reduce transfer size.
 
-    NOTE:
+    Arguments:
+        path: Local path to sync (default: current directory)
 
-        For most workflows, use 'plato sandbox start-services' instead,
-        which syncs files AND restarts containers.
+    Options:
+        -r, --remote-path: Destination path on the VM. Defaults to
+            /home/plato/worktree/<service> based on the service in .sandbox.yaml
+        -t, --timeout: Command timeout in seconds for the extract operation (default: 120)
+        -j, --json: Output results as JSON instead of formatted text
     """
     api_key = require_api_key()
     state = require_sandbox_state()
@@ -1367,41 +1359,25 @@ def sandbox_flow(
     local: bool = typer.Option(False, "--local", "-l", help="Force using local flows.yml only"),
     api: bool = typer.Option(False, "--api", "-a", help="Force fetching flows from API only"),
 ):
-    """
-    Execute a test flow against the running sandbox.
-
-    Runs a flow (like login) to verify it works before starting the worker.
-    Opens a browser and executes the flow steps automatically.
-
-    REQUIRES:
-
-        .sandbox.yaml in current directory (created by 'plato sandbox start')
-        Either:
-          - Local plato-config.yml with flows_path pointing to flows.yml
-          - Or sandbox started from artifact (flows fetched from API)
-
-    USAGE:
+    """Execute a test flow against the running sandbox.
 
-        plato sandbox flow                    # Run "login" flow (default)
-        plato sandbox flow -f login           # Explicit flow name
-        plato sandbox flow -f incorrect_login # Test failed login flow
-        plato sandbox flow --local            # Force local flows.yml
-        plato sandbox flow --api              # Force API flows (from artifact)
+    Runs a named flow (like "login") using Playwright to verify it works correctly.
+    Opens a visible browser window, navigates to the sandbox public URL, and executes
+    the flow steps automatically. Useful for testing login flows before starting
+    the worker.
 
-    WORKFLOW POSITION:
+    By default, looks for flows in local flows.yml (path from plato-config.yml
+    metadata.flows_path), then falls back to fetching from the API if the sandbox
+    was started from an artifact.
 
-        1. plato sandbox start -c
-        2. plato sandbox start-services
-        3. plato sandbox flow             ← you are here (verify login)
-        4. plato sandbox start-worker
-        5. plato sandbox snapshot
+    Options:
+        -f, --flow-name: Name of the flow to execute from flows.yml (default: "login")
+        -l, --local: Only use local flows.yml file. Errors if not found instead of
+            falling back to API.
+        -a, --api: Only fetch flows from the API (from the artifact). Ignores any
+            local flows.yml file.
 
-    FLOW SOURCE (default priority):
-
-        1. Local flows.yml (from plato-config.yml metadata.flows_path)
-        2. API (fetched from artifact if started from simulator)
-
-        Use --local or --api to override this behavior.
+    Note: --local and --api are mutually exclusive.
     """
     # Validate mutually exclusive flags
     if local and api:
@@ -1581,30 +1557,19 @@ def sandbox_state_cmd(
     ),
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ):
-    """
-    Get the database state/mutations from the simulator.
-
-    Shows what database changes have been detected since the last reset.
-    Useful during review to verify:
-      - No mutations after login (state should be empty)
-      - Mutations appear after making changes (audit is working)
-
-    REQUIRES:
-
-        .sandbox.yaml in current directory (created by 'plato sandbox start')
-
-    USAGE:
-
-        plato sandbox state                      # Show current state
-        plato sandbox state --verify-no-mutations  # Exit 1 if mutations found
-        plato sandbox state -v                   # Short form
-
-    USED DURING REVIEW:
-
-        1. Run login flow
-        2. plato sandbox state -v    ← should pass (no mutations)
-        3. Make a change in the app
-        4. plato sandbox state       ← should show mutations
+    """Get the database state/mutations from the simulator.
+
+    Queries the worker to show what database changes have been detected since the last
+    reset. Displays mutations grouped by table and operation type (INSERT/UPDATE/DELETE).
+    Useful for verifying that login flows don't cause unwanted database mutations and
+    that the audit system is properly tracking changes.
+
+    Options:
+        -v, --verify-no-mutations: Exit with code 1 if any mutations are detected.
+            Useful for CI/automation to verify login doesn't cause database changes.
+            If mutations are found, the exit code indicates failure.
+        -j, --json: Output the full state response as JSON instead of formatted text.
+            Includes has_mutations and has_error fields for scripting.
     """
     sandbox_state = require_sandbox_state()
     api_key = require_api_key()
@@ -1790,33 +1755,19 @@ def sandbox_clear_audit(
     dataset: str = typer.Option("base", "--dataset", "-d", help="Dataset name"),
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ):
-    """
-    Clear the audit_log table(s) in the sandbox database.
-
-    Truncates all audit_log tables to reset mutation tracking. Use this after
-    initial setup/login to clear any mutations before running a clean login flow.
-
-    REQUIRES:
+    """Clear the audit_log table(s) in the sandbox database.
 
-        .sandbox.yaml in current directory (created by 'plato sandbox start')
-        plato-config.yml with database listener config
+    Truncates all audit_log tables to reset mutation tracking. Use this after initial
+    setup or login has generated expected mutations, so you can verify that subsequent
+    login flows don't create new mutations.
 
-    USAGE:
+    Reads database connection info from plato-config.yml listeners and executes the
+    appropriate SQL (PostgreSQL TRUNCATE or MySQL DELETE) via SSH to the sandbox VM.
 
-        plato sandbox clear-audit                # Uses plato-config.yml in cwd
-        plato sandbox clear-audit -d base        # Specify dataset
-        plato sandbox clear-audit --json         # JSON output
-
-    WORKFLOW POSITION:
-
-        1. plato sandbox start -c
-        2. plato sandbox start-services
-        3. plato sandbox start-worker --wait
-        4. (agent does initial login/setup, generating mutations)
-        5. plato sandbox clear-audit            ← you are here
-        6. plato sandbox flow                   ← clean login flow
-        7. plato sandbox state --verify-no-mutations  ← should pass now
-        8. plato sandbox snapshot
+    Options:
+        --config-path: Path to plato-config.yml file (default: looks in current directory)
+        -d, --dataset: Dataset name to read listener configuration from (default: "base")
+        -j, --json: Output results as JSON instead of formatted text
     """
     state = require_sandbox_state()
 
@@ -1932,26 +1883,15 @@ def sandbox_clear_audit(
 
 @sandbox_app.command(name="audit-ui")
 def sandbox_audit_ui():
-    """
-    Launch Streamlit UI for configuring database audit rules.
-
-    Opens a visual interface to help configure audit_ignore_tables
-    in plato-config.yml. Useful when you see unwanted mutations
-    during review (like session tables, timestamps, etc.).
-
-    REQUIRES:
+    """Launch Streamlit UI for configuring database audit rules.
 
-        streamlit installed: pip install streamlit psycopg2-binary pymysql
+    Opens a visual web interface to help configure audit_ignore_tables in plato-config.yml.
+    The UI shows database tables and their recent mutations, making it easy to identify
+    which tables or columns should be ignored (like session tables, last_login timestamps,
+    etc. that change on every login).
 
-    USAGE:
-
-        plato sandbox audit-ui
-
-    WHEN TO USE:
-
-        - Review shows mutations after login (sessions, timestamps)
-        - Need to figure out which tables/columns to ignore
-        - Want visual help building audit_ignore_tables config
+    Requires streamlit and database drivers to be installed:
+        pip install streamlit psycopg2-binary pymysql
     """
     # Check if streamlit is installed
     if not shutil.which("streamlit"):
@@ -2117,40 +2057,20 @@ def _stop_heartbeat_process(pid: int) -> bool:
 def sandbox_start_services(
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ):
-    """
-    Deploy and start docker compose services on the sandbox.
-
-    Syncs your local code to the VM and starts the containers defined
-    in plato-config.yml. This is the main command for deploying your app.
-
-    REQUIRES:
-
-        .sandbox.yaml in current directory (created by 'plato sandbox start -c')
-        plato-config.yml with services defined
-
-    USAGE:
-
-        plato sandbox start-services           # Deploy and start containers
-        plato sandbox start-services --json    # JSON output
-
-    WHAT IT DOES:
-
-        1. Pushes local code to Plato Hub (Gitea)
-        2. Clones code on VM via SSH
-        3. Runs 'docker compose up -d' on VM
-        4. Waits for containers to be healthy
-
-    WORKFLOW POSITION:
+    """Deploy and start docker compose services on the sandbox.
 
-        1. plato sandbox start -c             ← creates VM
-        2. plato sandbox start-services       ← you are here (deploy app)
-        3. plato sandbox flow                 ← verify login
-        4. plato sandbox start-worker
-        5. plato sandbox snapshot
+    Syncs your local code to the sandbox VM and starts containers. The process:
+    1. Gets Gitea credentials and pushes local code to a new branch on Plato Hub
+    2. Clones the code on the VM via SSH
+    3. Runs 'docker compose up -d' for each docker-compose service defined in
+       the plato-config.yml services section
 
-    AFTER MAKING CHANGES:
+    Run this command again after making local changes to re-sync and restart containers.
+    Requires SSH to be configured (network is enabled by default).
 
-        Run this command again to re-sync and restart containers.
+    Options:
+        -j, --json: Output results as JSON instead of formatted text. Includes
+            branch name, repo URL, VM path, and list of services started.
     """
     api_key = require_api_key()
     state = require_sandbox_state()