arga-cli 0.1.4__tar.gz → 0.1.5__tar.gz

{arga_cli-0.1.4 → arga_cli-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arga-cli
-Version: 0.1.4
+Version: 0.1.5
 Summary: Command-line interface for Arga authentication, MCP installation, and browser validation
 Author: Arga Labs
 Project-URL: Homepage, https://github.com/ArgaLabs/arga-cli
@@ -17,6 +17,8 @@ Classifier: Topic :: Software Development
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.27.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=13.0.0
 
 # Arga CLI
 
@@ -87,6 +89,14 @@ Start a pull request validation run:
 arga validate pr --repo arga-labs/validation-server --pr 182
 ```
 
+Any of these commands accept `--json` for machine-parseable output:
+
+```bash
+arga test url --url https://demo-app.com --prompt "test login" --json
+arga runs list --json
+arga runs status <run_id> --json
+```
+
 Create a commit that skips Arga validation:
 
 ```bash
@@ -119,12 +129,6 @@ arga runs logs <run_id>
 arga runs cancel <run_id>
 ```
 
-`arga validate url` is also available and currently behaves the same as `arga test url`:
-
-```bash
-arga validate url --url https://demo-app.com --prompt "test checkout"
-```
-
 ## Command Reference
 
 ### Authentication
@@ -143,7 +147,6 @@ arga logout
 
 ```bash
 arga test url --url https://demo-app.com --prompt "test login flow"
-arga validate url --url https://demo-app.com --prompt "test checkout"
 arga validate pr --repo arga-labs/validation-server --pr 182
 arga validate install arga-labs/validation-server
 arga validate config arga-labs/validation-server
@@ -151,8 +154,9 @@ arga validate config set arga-labs/validation-server --trigger branch --branch m
 ```
 
 - `arga test url` starts a one-off validation against a deployed URL.
-- `arga validate url` is an equivalent URL-validation entry point under the `validate` namespace.
 - `arga validate pr` starts GitHub-backed PR validation for a repository and pull request number.
+
+Both accept `--json` to output `{"run_id": "...", "status": "..."}` instead of human-readable text.
 - `arga validate install <repo>` installs the GitHub webhook for automatic validation on a repository.
 - `arga validate config <repo>` shows the current automatic validation settings, including install state, trigger mode, selected branch, and PR comment behavior.
 - `arga validate config set <repo>` updates the automatic validation settings. Any omitted options keep their current value.
@@ -201,6 +205,8 @@ arga runs cancel <run_id>
 - Add `--errors-only` to keep only failed worker logs plus warning/error runtime entries.
 - `arga runs cancel <run_id>` cancels the run through the validation API.
 
+Both `runs list` and `runs status` accept `--json` for structured output.
+
 ### Git Wrappers
 
 ```bash
@@ -260,6 +266,42 @@ If you need to add the server manually, the generated config looks like:
 }
 ```
 
+## JSON Output
+
+Key commands support `--json` for use in CI pipelines, shell scripts, and agent automation:
+
+```bash
+# Capture the run ID from a validation
+RUN_ID=$(arga test url --url https://app.example.com --prompt "test login" --json | jq -r .run_id)
+
+# Poll run status as JSON
+arga runs status "$RUN_ID" --json | jq .status
+
+# List runs as a JSON array
+arga runs list --repo arga-labs/validation-server --json | jq '.[].run_id'
+
+# Start PR validation and capture result
+arga validate pr --repo arga-labs/validation-server --pr 182 --json
+```
+
+Commands that support `--json`:
+
+| Command | JSON shape |
+|---|---|
+| `arga test url` | `{"run_id": "...", "status": "..."}` |
+| `arga validate pr` | `{"run_id": "...", "status": "..."}` |
+| `arga runs status <id>` | Full run object |
+| `arga runs list` | Array of run summaries |
+
+## Example Project
+
+See [ArgaLabs/example-app](https://github.com/ArgaLabs/example-app) for a complete working example showing how to integrate Arga into a Next.js project with:
+
+- GitHub Actions CI validation on every PR
+- MCP config for Cursor and Claude Code
+- A shell script for manual validation
+- End-to-end walkthrough in the README
+
 ## Using A Custom API URL
 
 By default, the CLI targets `https://api.argalabs.com`.
@@ -270,7 +312,6 @@ To point it at another environment, pass `--api-url` or set `ARGA_API_URL`:
 arga login --api-url http://localhost:8000
 arga mcp install --api-url http://localhost:8000
 arga test url --api-url http://localhost:8000 --url https://demo-app.com --prompt "test checkout"
-arga validate url --api-url http://localhost:8000 --url https://demo-app.com --prompt "test checkout"
 arga validate pr --api-url http://localhost:8000 --repo arga-labs/validation-server --pr 182
 ```
 

{arga_cli-0.1.4 → arga_cli-0.1.5}/README.md

@@ -67,6 +67,14 @@ Start a pull request validation run:
 arga validate pr --repo arga-labs/validation-server --pr 182
 ```
 
+Any of these commands accept `--json` for machine-parseable output:
+
+```bash
+arga test url --url https://demo-app.com --prompt "test login" --json
+arga runs list --json
+arga runs status <run_id> --json
+```
+
 Create a commit that skips Arga validation:
 
 ```bash
@@ -99,12 +107,6 @@ arga runs logs <run_id>
 arga runs cancel <run_id>
 ```
 
-`arga validate url` is also available and currently behaves the same as `arga test url`:
-
-```bash
-arga validate url --url https://demo-app.com --prompt "test checkout"
-```
-
 ## Command Reference
 
 ### Authentication
@@ -123,7 +125,6 @@ arga logout
 
 ```bash
 arga test url --url https://demo-app.com --prompt "test login flow"
-arga validate url --url https://demo-app.com --prompt "test checkout"
 arga validate pr --repo arga-labs/validation-server --pr 182
 arga validate install arga-labs/validation-server
 arga validate config arga-labs/validation-server
@@ -131,8 +132,9 @@ arga validate config set arga-labs/validation-server --trigger branch --branch m
 ```
 
 - `arga test url` starts a one-off validation against a deployed URL.
-- `arga validate url` is an equivalent URL-validation entry point under the `validate` namespace.
 - `arga validate pr` starts GitHub-backed PR validation for a repository and pull request number.
+
+Both accept `--json` to output `{"run_id": "...", "status": "..."}` instead of human-readable text.
 - `arga validate install <repo>` installs the GitHub webhook for automatic validation on a repository.
 - `arga validate config <repo>` shows the current automatic validation settings, including install state, trigger mode, selected branch, and PR comment behavior.
 - `arga validate config set <repo>` updates the automatic validation settings. Any omitted options keep their current value.
@@ -181,6 +183,8 @@ arga runs cancel <run_id>
 - Add `--errors-only` to keep only failed worker logs plus warning/error runtime entries.
 - `arga runs cancel <run_id>` cancels the run through the validation API.
 
+Both `runs list` and `runs status` accept `--json` for structured output.
+
 ### Git Wrappers
 
 ```bash
@@ -240,6 +244,42 @@ If you need to add the server manually, the generated config looks like:
 }
 ```
 
+## JSON Output
+
+Key commands support `--json` for use in CI pipelines, shell scripts, and agent automation:
+
+```bash
+# Capture the run ID from a validation
+RUN_ID=$(arga test url --url https://app.example.com --prompt "test login" --json | jq -r .run_id)
+
+# Poll run status as JSON
+arga runs status "$RUN_ID" --json | jq .status
+
+# List runs as a JSON array
+arga runs list --repo arga-labs/validation-server --json | jq '.[].run_id'
+
+# Start PR validation and capture result
+arga validate pr --repo arga-labs/validation-server --pr 182 --json
+```
+
+Commands that support `--json`:
+
+| Command | JSON shape |
+|---|---|
+| `arga test url` | `{"run_id": "...", "status": "..."}` |
+| `arga validate pr` | `{"run_id": "...", "status": "..."}` |
+| `arga runs status <id>` | Full run object |
+| `arga runs list` | Array of run summaries |
+
+## Example Project
+
+See [ArgaLabs/example-app](https://github.com/ArgaLabs/example-app) for a complete working example showing how to integrate Arga into a Next.js project with:
+
+- GitHub Actions CI validation on every PR
+- MCP config for Cursor and Claude Code
+- A shell script for manual validation
+- End-to-end walkthrough in the README
+
 ## Using A Custom API URL
 
 By default, the CLI targets `https://api.argalabs.com`.
@@ -250,7 +290,6 @@ To point it at another environment, pass `--api-url` or set `ARGA_API_URL`:
 arga login --api-url http://localhost:8000
 arga mcp install --api-url http://localhost:8000
 arga test url --api-url http://localhost:8000 --url https://demo-app.com --prompt "test checkout"
-arga validate url --api-url http://localhost:8000 --url https://demo-app.com --prompt "test checkout"
 arga validate pr --api-url http://localhost:8000 --repo arga-labs/validation-server --pr 182
 ```
 

{arga_cli-0.1.4 → arga_cli-0.1.5}/arga_cli/main.py

@@ -85,6 +85,7 @@ class ApiClient:
         prompt: str,
         email: str | None = None,
         password: str | None = None,
+        ttl_minutes: int | None = None,
     ) -> dict[str, str]:
         payload: dict[str, object] = {
             "url": url,
@@ -95,6 +96,8 @@ class ApiClient:
                 "email": email or "",
                 "password": password or "",
             }
+        if ttl_minutes is not None:
+            payload["ttl_minutes"] = ttl_minutes
         response = self._client.post(
             f"{self._api_url}/validate/url",
             json=payload,
@@ -398,9 +401,34 @@ def run_whoami(args: argparse.Namespace) -> int:
         elif billing_plan in ("team", "paid"):
             print("Twins per run: unlimited")
 
+        max_ttl = plan_limits.get("max_ttl_minutes")
+        if max_ttl is not None:
+            print(f"Max run TTL: {max_ttl} minutes")
+        elif billing_plan in ("team", "paid"):
+            print("Max run TTL: 480 minutes")
+
     return 0
 
 
+def _resolve_ttl(client: ApiClient, requested_ttl: int | None) -> int | None:
+    """Resolve TTL based on user plan. Free users are capped at 10 minutes."""
+    FREE_TTL = 10
+
+    me = client.get_me()
+    billing_plan = me.get("billing_plan", "free")
+
+    if billing_plan in ("team", "paid"):
+        return requested_ttl  # None means server default (30 min)
+
+    # Free tier — locked to 10 minutes
+    if requested_ttl is not None and requested_ttl != FREE_TTL:
+        raise CliError(
+            f"Free plan runs are limited to {FREE_TTL} minutes. "
+            f"Upgrade to Team for custom TTL (up to 480 minutes)."
+        )
+    return FREE_TTL
+
+
 def run_test_url(args: argparse.Namespace) -> int:
     if bool(args.email) != bool(args.password):
         raise CliError("Both --email and --password must be provided together.")
@@ -408,11 +436,13 @@ def run_test_url(args: argparse.Namespace) -> int:
     api_key = load_api_key()
     client = ApiClient(args.api_url, api_key=api_key)
     try:
+        ttl_minutes = _resolve_ttl(client, getattr(args, "ttl", None))
         payload = client.start_url_validation(
             url=args.url,
             prompt=args.prompt,
             email=args.email,
             password=args.password,
+            ttl_minutes=ttl_minutes,
         )
     finally:
         client.close()
@@ -423,7 +453,8 @@ def run_test_url(args: argparse.Namespace) -> int:
 
     print("Starting validation...\n")
     print(f"URL: {args.url}")
-    print(f"Prompt: {args.prompt}\n")
+    print(f"Prompt: {args.prompt}")
+    print(f"TTL: {ttl_minutes} minutes\n")
     print(f"Run ID: {payload.get('run_id', 'unknown')}")
     print(f"Status: {payload.get('status', 'unknown')}")
     return 0
@@ -453,7 +484,6 @@ def run_validate_pr(args: argparse.Namespace) -> int:
 def _validate_help_text() -> str:
     return (
         "usage: arga validate pr --repo <owner/repo> --pr <number>\n"
-        "       arga validate url --url <url> --prompt <prompt>\n"
         "       arga validate install <repo>\n"
         "       arga validate config <repo>\n"
         "       arga validate config set <repo> [--trigger pr|branch] [--branch <name>] [--comments on|off]\n\n"
@@ -473,20 +503,6 @@ def _build_validate_pr_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def _build_validate_url_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        prog="arga validate url",
-        description="Run a browser validation against a deployed URL.",
-        allow_abbrev=False,
-    )
-    parser.add_argument("--api-url", default=DEFAULT_API_URL, help="Arga API base URL")
-    parser.add_argument("--url", required=True, help="Deployed application URL")
-    parser.add_argument("--prompt", required=True, help="Natural language instructions for the agent")
-    parser.add_argument("--email", help="Optional login email")
-    parser.add_argument("--password", help="Optional login password")
-    return parser
-
-
 def _build_validate_install_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="arga validate install",
@@ -575,11 +591,7 @@ def run_validate_config_set(args: argparse.Namespace) -> int:
     try:
         current = client.get_github_validation_config(repo=args.repo)
         trigger_mode = args.trigger or str(current.get("trigger_mode") or "pr")
-        comment_on_pr = (
-            current.get("comment_on_pr", True)
-            if args.comments is None
-            else args.comments == "on"
-        )
+        comment_on_pr = current.get("comment_on_pr", True) if args.comments is None else args.comments == "on"
         branch: str | None = None
         if trigger_mode == "branch":
             branch = args.branch or str(current.get("branch") or current.get("default_branch") or "").strip() or None
@@ -677,16 +689,12 @@ def _wait_for_scan_approval(client: ApiClient, run_id: str) -> dict[str, Any]:
 
         time.sleep(POLL_INTERVAL_SECONDS)
 
-    raise CliError(
-        f"Timed out waiting for the scan plan to be ready for run {last_run.get('id', run_id)}."
-    )
+    raise CliError(f"Timed out waiting for the scan plan to be ready for run {last_run.get('id', run_id)}.")
 
 
 def _print_scan_summary(run_id: str, run: dict[str, Any]) -> None:
     report = run.get("redteam_report_json")
-    anomaly_count = (
-        len(report.get("anomalies") or []) if isinstance(report, dict) else 0
-    )
+    anomaly_count = len(report.get("anomalies") or []) if isinstance(report, dict) else 0
     print(f"Run ID: {run_id}")
     print(f"Status: {_status_from_run(run)}")
     print(f"URL: {run.get('frontend_url') or run.get('pr_url') or 'unknown'}")
@@ -833,8 +841,7 @@ def _print_runs_table(runs: list[dict[str, Any]]) -> None:
         for run in runs
     ]
     widths = [
-        max(len(headers[index]), max((len(row[index]) for row in rows), default=0))
-        for index in range(len(headers))
+        max(len(headers[index]), max((len(row[index]) for row in rows), default=0)) for index in range(len(headers))
     ]
 
     def format_row(values: list[str]) -> str:
@@ -1068,8 +1075,6 @@ def run_validate_cli(argv: list[str]) -> int:
 
     if argv[0] == "pr":
         return run_validate_pr(_build_validate_pr_parser().parse_args(argv[1:]))
-    if argv[0] == "url":
-        return run_test_url(_build_validate_url_parser().parse_args(argv[1:]))
     if argv[0] == "install":
         return run_validate_install(_build_validate_install_parser().parse_args(argv[1:]))
     if argv[0] == "config":
@@ -1152,9 +1157,7 @@ def _build_skip_commit_args(git_args: list[str]) -> tuple[list[str], str | None,
 
     file_path = _extract_commit_file_path(git_args)
     if file_path is None:
-        raise CliError(
-            "Error: `arga commit --skip` requires a commit message via `-m/--message` or `-F/--file`."
-        )
+        raise CliError("Error: `arga commit --skip` requires a commit message via `-m/--message` or `-F/--file`.")
 
     if file_path == "-":
         stdin_message = sys.stdin.read()
@@ -1224,26 +1227,215 @@ def run_push_cli(argv: list[str]) -> int:
     return _run_git_command(["push", *git_args])
 
 
-def run_wizard(args: argparse.Namespace) -> int:
-    """Launch the arga-wizard npm package, passing the stored API key."""
+def _wizard_help_text() -> str:
+    return (
+        "usage: arga wizard [command] [options]\n\n"
+        "Commands:\n"
+        "  init        Run the quickstart wizard (default)\n"
+        "  status      Check twin session health\n"
+        "  reset       Reset all twins to seed state\n"
+        "  extend      Extend session by 10 minutes\n"
+        "  teardown    Destroy session and clean up\n"
+        "  env         Re-run .env rewriting step\n\n"
+        "Options:\n"
+        "  --api-url            API base URL\n"
+        "  --no-shape-detect    Disable heuristic detection of API keys by value pattern\n"
+        "  -h, --help           Show this help"
+    )
+
+
+def _build_wizard_init_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="arga wizard", allow_abbrev=False)
+    parser.add_argument("--api-url", default=DEFAULT_API_URL, help="Arga API base URL")
+    parser.add_argument("--no-shape-detect", action="store_true", default=False)
+    return parser
+
+
+def _build_wizard_session_parser(prog: str) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog=prog, allow_abbrev=False)
+    parser.add_argument("--api-url", default=DEFAULT_API_URL, help="Arga API base URL")
+    return parser
+
+
+def run_wizard_init(args: argparse.Namespace) -> int:
+    """Run the full quickstart wizard natively."""
+    from arga_cli.wizard import run_wizard
+
     try:
         api_key = load_api_key()
     except (NotAuthenticatedError, CliError):
-        print("Not logged in. Run `arga login` first, or use `npx arga-wizard` directly.")
+        api_key = None
+
+    return run_wizard(
+        api_url=args.api_url,
+        api_key=api_key,
+        cwd=os.getcwd(),
+        shape_detect=not getattr(args, "no_shape_detect", False),
+    )
+
+
+def run_wizard_status(_args: argparse.Namespace) -> int:
+    from arga_cli.wizard.constants import TWIN_CATALOG
+    from arga_cli.wizard.output import print_summary_box
+    from arga_cli.wizard.provision import with_proxy_token
+    from arga_cli.wizard.session import load_session
+
+    session = load_session(os.getcwd())
+    client = ApiClient(session["api_url"], api_key=session["api_key"])
+    try:
+        response = client._client.get(
+            f"{client._api_url}/validate/twins/provision/{session['run_id']}/status",
+            headers=client._auth_headers(),
+        )
+        status = client._parse_json(response, "Failed to get status")
+    finally:
+        client.close()
+
+    lines = [
+        "[bold]Twin Session Status[/bold]",
+        "",
+        f"Run ID:  {status['run_id']}",
+        f"Status:  {'[green]' + status['status'] + '[/green]' if status['status'] == 'ready' else '[yellow]' + status['status'] + '[/yellow]'}",
+        "",
+    ]
+    for name, info in status.get("twins", {}).items():
+        label = TWIN_CATALOG.get(name, {}).get("label", name).ljust(16)
+        url = with_proxy_token(info.get("base_url", ""), status.get("proxy_token"))
+        lines.append(f"{label} [underline]{url}[/underline]")
+    if status.get("expires_at"):
+        lines.append("")
+        lines.append(f"Expires: {status['expires_at']}")
+    print_summary_box(lines)
+    return 0
+
+
+def run_wizard_reset(_args: argparse.Namespace) -> int:
+    from arga_cli.wizard.constants import TWIN_CATALOG
+    from arga_cli.wizard.output import console, green, header
+    from arga_cli.wizard.provision import with_proxy_token
+    from arga_cli.wizard.session import load_session
+
+    session = load_session(os.getcwd())
+    client = ApiClient(session["api_url"], api_key=session["api_key"])
+    header("Resetting all twins...")
+
+    twins = session.get("twins", {})
+    proxy_token = session.get("proxy_token")
+
+    # Refresh from API if possible
+    try:
+        response = client._client.get(
+            f"{client._api_url}/validate/twins/provision/{session['run_id']}/status",
+            headers=client._auth_headers(),
+        )
+        status = client._parse_json(response, "Failed to get status")
+        if status.get("status") == "ready":
+            twins = {
+                name: {"base_url": info.get("base_url", ""), "admin_url": info.get("admin_url", "")}
+                for name, info in status.get("twins", {}).items()
+            }
+            proxy_token = status.get("proxy_token", proxy_token)
+    except Exception:
+        pass
+
+    for name, twin in twins.items():
+        label = TWIN_CATALOG.get(name, {}).get("label", name)
+        try:
+            reset_url = with_proxy_token(f"{twin['admin_url']}/admin/reset", proxy_token)
+            client._client.post(reset_url, json={}, headers={"Content-Type": "application/json"})
+            console.print(f"  {label}: [green]reset[/green]")
+        except Exception as exc:
+            console.print(f"  {label}: [red]failed \u2014 {exc}[/red]")
+
+    client.close()
+    green("\nDone.")
+    return 0
+
+
+def run_wizard_extend(_args: argparse.Namespace) -> int:
+    from arga_cli.wizard.output import error, green
+    from arga_cli.wizard.session import load_session
+
+    session = load_session(os.getcwd())
+    client = ApiClient(session["api_url"], api_key=session["api_key"])
+    try:
+        response = client._client.post(
+            f"{client._api_url}/validate/twins/provision/{session['run_id']}/extend",
+            json={"ttl_minutes": 10},
+            headers=client._auth_headers(),
+        )
+        client._parse_json(response, "Failed to extend session")
+        green("\nSession extended by 10 minutes.")
+    except Exception as exc:
+        error(f"Failed to extend: {exc}")
         return 1
+    finally:
+        client.close()
+    return 0
+
 
-    cmd: list[str] = ["npx", "arga-wizard"]
-    cmd.extend(["--api-key", api_key])
-    if args.api_url != DEFAULT_API_URL:
-        cmd.extend(["--api-url", args.api_url])
+def run_wizard_teardown(_args: argparse.Namespace) -> int:
+    from arga_cli.wizard.output import error, green
+    from arga_cli.wizard.session import delete_session, load_session
 
+    session = load_session(os.getcwd())
+    client = ApiClient(session["api_url"], api_key=session["api_key"])
     try:
-        result = subprocess.run(cmd, check=False)
-        return result.returncode
-    except FileNotFoundError:
-        print("Node.js is required for the wizard. Install it from https://nodejs.org")
-        print("Or run the wizard directly: npx arga-wizard")
+        response = client._client.post(
+            f"{client._api_url}/validate/{session['run_id']}/cancel",
+            headers=client._auth_headers(),
+        )
+        client._parse_json(response, "Failed to cancel run")
+        delete_session(os.getcwd())
+        green("\nSession destroyed. .arga-session.json removed.")
+    except Exception as exc:
+        error(f"Failed to teardown: {exc}")
         return 1
+    finally:
+        client.close()
+    return 0
+
+
+def run_wizard_env(args: argparse.Namespace) -> int:
+    from arga_cli.wizard.env import rewrite_env_files
+    from arga_cli.wizard.prompts import select_twins
+
+    selected = select_twins()
+    if not selected:
+        return 1
+    rewrite_env_files(
+        os.getcwd(),
+        selected,
+        shape_detect=not getattr(args, "no_shape_detect", False),
+    )
+    return 0
+
+
+def run_wizard_cli(argv: list[str]) -> int:
+    if not argv or argv[0] in {"-h", "--help"}:
+        print(_wizard_help_text())
+        return 0
+
+    command = argv[0]
+
+    if command == "init":
+        return run_wizard_init(_build_wizard_init_parser().parse_args(argv[1:]))
+    if command == "status":
+        return run_wizard_status(_build_wizard_session_parser("arga wizard status").parse_args(argv[1:]))
+    if command == "reset":
+        return run_wizard_reset(_build_wizard_session_parser("arga wizard reset").parse_args(argv[1:]))
+    if command == "extend":
+        return run_wizard_extend(_build_wizard_session_parser("arga wizard extend").parse_args(argv[1:]))
+    if command == "teardown":
+        return run_wizard_teardown(_build_wizard_session_parser("arga wizard teardown").parse_args(argv[1:]))
+    if command == "env":
+        return run_wizard_env(_build_wizard_init_parser().parse_args(argv[1:]))
+
+    # No recognized subcommand — treat everything as flags for `init`
+    if command.startswith("-"):
+        return run_wizard_init(_build_wizard_init_parser().parse_args(argv))
+
+    raise CliError(f"Unknown wizard subcommand: {command}")
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -1276,6 +1468,12 @@ def build_parser() -> argparse.ArgumentParser:
     test_url_parser.add_argument("--prompt", required=True, help="Natural language instructions for the agent")
     test_url_parser.add_argument("--email", help="Optional login email")
     test_url_parser.add_argument("--password", help="Optional login password")
+    test_url_parser.add_argument(
+        "--ttl",
+        type=int,
+        default=None,
+        help="Run duration in minutes (Team/Paid: 1-480, default 30; Free: fixed at 10)",
+    )
     test_url_parser.add_argument("--json", action="store_true", default=False, help="Output result as JSON")
     test_url_parser.set_defaults(func=run_test_url)
 
@@ -1289,18 +1487,6 @@ def build_parser() -> argparse.ArgumentParser:
     validate_pr_parser.add_argument("--json", action="store_true", default=False, help="Output result as JSON")
     validate_pr_parser.set_defaults(func=run_validate_pr)
 
-    validate_url_parser = validate_subparsers.add_parser(
-        "url",
-        help="Run a browser validation against a deployed URL",
-    )
-    validate_url_parser.add_argument("--api-url", default=DEFAULT_API_URL, help="Arga API base URL")
-    validate_url_parser.add_argument("--url", required=True, help="Deployed application URL")
-    validate_url_parser.add_argument("--prompt", required=True, help="Natural language instructions for the agent")
-    validate_url_parser.add_argument("--email", help="Optional login email")
-    validate_url_parser.add_argument("--password", help="Optional login password")
-    validate_url_parser.add_argument("--json", action="store_true", default=False, help="Output result as JSON")
-    validate_url_parser.set_defaults(func=run_test_url)
-
     mcp_parser = subparsers.add_parser("mcp", help="Manage MCP integrations")
     mcp_subparsers = mcp_parser.add_subparsers(dest="mcp_command", required=True)
 
@@ -1352,9 +1538,7 @@ def build_parser() -> argparse.ArgumentParser:
     runs_cancel_parser.add_argument("run_id", help="Validation run ID")
     runs_cancel_parser.set_defaults(func=run_runs_cancel)
 
-    wizard_parser = subparsers.add_parser("wizard", help="Launch the twins quickstart wizard")
-    wizard_parser.add_argument("--api-url", default=DEFAULT_API_URL, help="Arga API base URL")
-    wizard_parser.set_defaults(func=run_wizard)
+    subparsers.add_parser("wizard", help="Twins quickstart wizard (run `arga wizard --help` for subcommands)")
 
     subparsers.add_parser("commit", help="Wrap git commit and optionally mark it to skip Arga validation")
     subparsers.add_parser("push", help="Wrap git push and verify skip state when requested")
@@ -1372,6 +1556,8 @@ def main() -> None:
             exit_code = run_validate_cli(sys.argv[2:])
         elif len(sys.argv) > 1 and sys.argv[1] == "scan":
             exit_code = run_scan_cli(sys.argv[2:])
+        elif len(sys.argv) > 1 and sys.argv[1] == "wizard":
+            exit_code = run_wizard_cli(sys.argv[2:])
         else:
             parser = build_parser()
             args = parser.parse_args()