synth-ai 0.2.9.dev0__py3-none-any.whl → 0.2.23.dev3__py3-none-any.whl

synth_ai/demos/core/cli.py

@@ -1,25 +1,26 @@
 from __future__ import annotations
 
-import argparse
+import contextlib
 import json
 import os
-import sys
-import time
-from pathlib import Path
-from typing import Any, Dict, Callable
 import shutil
 import stat
+import sys
 import textwrap
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
 
-from synth_ai.demos.demo_task_apps import core as demo_core
-from synth_ai.demos.demo_task_apps.core import DemoEnv, DEFAULT_TASK_APP_SECRET_NAME
 from synth_ai.demo_registry import (
-    CopySpec,
     DemoTemplate,
     get_demo_template,
     list_demo_templates,
 )
-from synth_ai.handshake import run_handshake, HandshakeError
+from synth_ai.demos.demo_task_apps import core as demo_core
+from synth_ai.demos.demo_task_apps.core import DEFAULT_TASK_APP_SECRET_NAME, DemoEnv
+from synth_ai.handshake import HandshakeError, run_handshake
+from synth_ai.utils.process import get_subprocess_env, should_filter_log_line
 
 
 def _key_preview(value: str, label: str) -> str:
@@ -44,35 +45,71 @@ def _is_modal_public_url(u: str) -> bool:
         return False
 
 
-def cmd_setup(_args: argparse.Namespace) -> int:
-    # 1) Always perform SDK handshake and overwrite .env with returned keys
+def setup() -> int:
+    # Change to demo directory if stored
+    demo_dir = demo_core.load_demo_dir()
+    if demo_dir and os.path.isdir(demo_dir):
+        os.chdir(demo_dir)
+        print(f"Using demo directory: {demo_dir}")
+
+    # 1) Try to fetch keys from frontend; fall back to manual input if fetch fails
+    synth_key = ""
+    rl_env_key = ""
+    org_name = "this organization"
+
     try:
         print("\n⏳ Connecting SDK to your browser session…")
         res = run_handshake()
-        user = res.get("user") or {}
         org = res.get("org") or {}
         keys = res.get("keys") or {}
         synth_key = str(keys.get("synth") or "").strip()
         rl_env_key = str(keys.get("rl_env") or "").strip()
-        if not synth_key or not rl_env_key:
-            raise HandshakeError("handshake returned missing keys")
-        # Overwrite .env with the latest values from the account/org
-        demo_core.persist_dotenv_values({
+        org_name = org.get("name") or "this organization"
+        print(f"✅ Connected to {org_name}!")
+    except (HandshakeError, Exception) as e:
+        print(f"⚠️  Failed to fetch keys from frontend: {e}")
+        print("Falling back to manual entry...")
+
+    # Prompt for manual input if any key is missing
+    if not synth_key:
+        try:
+            synth_key = input(
+                "Failed to fetch your Synth API key. Please enter your Synth API key here:\n> "
+            ).strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nSetup cancelled.")
+            return 1
+        if not synth_key:
+            print("Synth API key is required.")
+            return 1
+
+    if not rl_env_key:
+        try:
+            rl_env_key = input(
+                "Failed to fetch your RL Environment API key. Please enter your RL Environment API key here:\n> "
+            ).strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nSetup cancelled.")
+            return 1
+        if not rl_env_key:
+            print("RL Environment API key is required.")
+            return 1
+
+    # Persist both keys to .env
+    dotenv_path = demo_core.persist_dotenv_values(
+        {
             "SYNTH_API_KEY": synth_key,
             "ENVIRONMENT_API_KEY": rl_env_key,
-        })
-        org_name = (org.get("name") or "this organization")
-        print(f"✅ Connected to {org_name}!")
-    except HandshakeError as e:
-        print(f"Handshake failed: {e}")
-        return 1
-    except Exception as e:
-        print(f"Unexpected handshake error: {e}")
-        return 1
+        }
+    )
+
+    # Store .env path for subsequent commands
+    demo_core.persist_env_file_path(dotenv_path)
 
     # 2) Reload env after handshake to pick up values from .env (suppress env prints)
-    import io
     import contextlib
+    import io
+
     _buf = io.StringIO()
     with contextlib.redirect_stdout(_buf):
         env = demo_core.load_env()
@@ -89,22 +126,22 @@ def cmd_setup(_args: argparse.Namespace) -> int:
             return
         current = env.task_app_base_url
         needs_lookup = False
-        if not current:
-            needs_lookup = True
-        elif not _is_modal_public_url(current):
+        if not current or not _is_modal_public_url(current):
             needs_lookup = True
         if not needs_lookup:
             return
-        code, out = _popen_capture([
-            "uv",
-            "run",
-            "python",
-            "-m",
-            "modal",
-            "app",
-            "url",
-            env.task_app_name,
-        ])
+        code, out = _popen_capture(
+            [
+                "uv",
+                "run",
+                "python",
+                "-m",
+                "modal",
+                "app",
+                "url",
+                env.task_app_name,
+            ]
+        )
         if code != 0 or not out:
             return
         new_url = ""
@@ -134,15 +171,16 @@ def cmd_setup(_args: argparse.Namespace) -> int:
 
     _maybe_fix_task_url()
 
-    ok_backend = False
-    ok_task = False
     if env.dev_backend_url:
-        api = env.dev_backend_url.rstrip("/") + ("" if env.dev_backend_url.endswith("/api") else "/api")
-        ok_backend = demo_core.assert_http_ok(api + "/health", method="GET")
+        api = env.dev_backend_url.rstrip("/") + (
+            "" if env.dev_backend_url.endswith("/api") else "/api"
+        )
+        demo_core.assert_http_ok(api + "/health", method="GET")
         # Intentionally suppress backend health print for concise output
     if env.task_app_base_url:
-        ok_task = demo_core.assert_http_ok(env.task_app_base_url.rstrip("/") + "/health", method="GET") or \
-                  demo_core.assert_http_ok(env.task_app_base_url.rstrip("/"), method="GET")
+        demo_core.assert_http_ok(
+            env.task_app_base_url.rstrip("/") + "/health", method="GET"
+        ) or demo_core.assert_http_ok(env.task_app_base_url.rstrip("/"), method="GET")
         # Intentionally suppress task app health print
     else:
         print("\nSet your task app URL by running:\nuvx synth-ai rl_demo deploy\n")
@@ -150,13 +188,19 @@ def cmd_setup(_args: argparse.Namespace) -> int:
     # Omit uv version print to keep output concise
 
     # Keep exit code neutral; not all checks are critical for pairing
+    print(f"\nKeys saved to: {dotenv_path}")
     return 0
 
 
-def _popen_capture(cmd: list[str], cwd: str | None = None, env: dict | None = None) -> tuple[int, str]:
+def _popen_capture(
+    cmd: list[str], cwd: str | None = None, env: dict | None = None
+) -> tuple[int, str]:
     import subprocess
+
     try:
-        proc = subprocess.Popen(cmd, cwd=cwd, env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
+        proc = subprocess.Popen(
+            cmd, cwd=cwd, env=get_subprocess_env(env), stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True
+        )
         out, _ = proc.communicate()
         return int(proc.returncode or 0), out or ""
     except Exception as e:
@@ -173,7 +217,7 @@ def _popen_stream(cmd: list[str], cwd: str | None = None, env: dict | None = Non
         proc = subprocess.Popen(
             cmd,
             cwd=cwd,
-            env=env,
+            env=get_subprocess_env(env),
             stdout=subprocess.PIPE,
             stderr=subprocess.STDOUT,
             text=True,
@@ -186,7 +230,8 @@ def _popen_stream(cmd: list[str], cwd: str | None = None, env: dict | None = Non
     def _pump(stdout) -> None:
         try:
             for line in stdout:
-                print(line.rstrip())
+                if not should_filter_log_line(line):
+                    print(line.rstrip())
         except Exception:
             pass
 
@@ -200,7 +245,9 @@ def _popen_stream(cmd: list[str], cwd: str | None = None, env: dict | None = Non
     return int(proc.returncode or 0)
 
 
-def _popen_stream_capture(cmd: list[str], cwd: str | None = None, env: dict | None = None) -> tuple[int, str]:
+def _popen_stream_capture(
+    cmd: list[str], cwd: str | None = None, env: dict | None = None
+) -> tuple[int, str]:
     """Stream subprocess output to stdout and also capture it into a buffer."""
     import subprocess
     import threading
@@ -210,7 +257,7 @@ def _popen_stream_capture(cmd: list[str], cwd: str | None = None, env: dict | No
         proc = subprocess.Popen(
             cmd,
             cwd=cwd,
-            env=env,
+            env=get_subprocess_env(env),
             stdout=subprocess.PIPE,
             stderr=subprocess.STDOUT,
             text=True,
@@ -224,8 +271,9 @@ def _popen_stream_capture(cmd: list[str], cwd: str | None = None, env: dict | No
         try:
             for line in stdout:
                 line = line.rstrip()
-                print(line)
-                buf_lines.append(line)
+                if not should_filter_log_line(line):
+                    print(line)
+                    buf_lines.append(line)
         except Exception:
             pass
 
@@ -251,7 +299,19 @@ def _find_asgi_apps(root: Path) -> list[Path]:
       - "@modal.asgi_app()"
     """
     results: list[Path] = []
-    skip_dirs = {".git", ".hg", ".svn", "node_modules", "dist", "build", "__pycache__", ".ruff_cache", ".mypy_cache", "venv", ".venv"}
+    skip_dirs = {
+        ".git",
+        ".hg",
+        ".svn",
+        "node_modules",
+        "dist",
+        "build",
+        "__pycache__",
+        ".ruff_cache",
+        ".mypy_cache",
+        "venv",
+        ".venv",
+    }
     for dirpath, dirnames, filenames in os.walk(root):
         dirnames[:] = [d for d in dirnames if d not in skip_dirs]
         for name in filenames:
@@ -265,16 +325,20 @@ def _find_asgi_apps(root: Path) -> list[Path]:
                     results.append(path)
             except Exception:
                 continue
+
     # Stable order: prioritize files under synth_demo/ first, then alphabetical
     def _priority(p: Path) -> tuple[int, str]:
         rel = str(p.resolve())
         in_demo = "/synth_demo/" in rel or rel.endswith("/synth_demo/task_app.py")
         return (0 if in_demo else 1, rel)
+
     results.sort(key=_priority)
     return results
 
 
-def _prompt_value(label: str, default: str | int | float, cast: Callable[[str], Any] | None = None) -> Any:
+def _prompt_value(
+    label: str, default: str | int | float, cast: Callable[[str], Any] | None = None
+) -> Any:
     prompt = f"{label} [{default}]: "
     try:
         raw = input(prompt).strip()
@@ -293,7 +357,19 @@ def _prompt_value(label: str, default: str | int | float, cast: Callable[[str],
 
 def _find_vllm_tomls(root: Path) -> list[Path]:
     results: list[Path] = []
-    skip_dirs = {".git", ".hg", ".svn", "node_modules", "dist", "build", "__pycache__", ".ruff_cache", ".mypy_cache", "venv", ".venv"}
+    skip_dirs = {
+        ".git",
+        ".hg",
+        ".svn",
+        "node_modules",
+        "dist",
+        "build",
+        "__pycache__",
+        ".ruff_cache",
+        ".mypy_cache",
+        "venv",
+        ".venv",
+    }
     for dirpath, dirnames, filenames in os.walk(root):
         dirnames[:] = [d for d in dirnames if d not in skip_dirs]
         for name in filenames:
@@ -313,7 +389,9 @@ def _create_new_config(env: DemoEnv) -> str:
     default_path = os.path.join(os.getcwd(), "demo_config.toml")
     while True:
         try:
-            destination = input(f"Path to save new config [{default_path}]: ").strip() or default_path
+            destination = (
+                input(f"Path to save new config [{default_path}]: ").strip() or default_path
+            )
         except Exception:
             destination = default_path
         destination = os.path.abspath(destination)
@@ -322,7 +400,9 @@ def _create_new_config(env: DemoEnv) -> str:
             continue
         if os.path.exists(destination):
             try:
-                overwrite = input(f"{destination} exists. Overwrite? [y/N]: ").strip().lower() or "n"
+                overwrite = (
+                    input(f"{destination} exists. Overwrite? [y/N]: ").strip().lower() or "n"
+                )
             except Exception:
                 overwrite = "n"
             if not overwrite.startswith("y"):
@@ -334,7 +414,9 @@ def _create_new_config(env: DemoEnv) -> str:
     model_name = _prompt_value("Model name", "Qwen/Qwen3-0.6B")
     compute_gpu_type = _prompt_value("Compute GPU type", "H100")
     compute_gpu_count = _prompt_value("Compute GPU count", 4, int)
-    topology_gpu_type = _prompt_value("Topology GPU type", f"{compute_gpu_type}:{compute_gpu_count}")
+    topology_gpu_type = _prompt_value(
+        "Topology GPU type", f"{compute_gpu_type}:{compute_gpu_count}"
+    )
     gpus_for_vllm = _prompt_value("Topology gpus_for_vllm", 2, int)
     gpus_for_training = _prompt_value("Topology gpus_for_training", 1, int)
     tensor_parallel = _prompt_value("Topology tensor_parallel", 2, int)
@@ -352,8 +434,9 @@ def _create_new_config(env: DemoEnv) -> str:
     task_url_default = env.task_app_base_url or ""
     services_task_url = _prompt_value("services.task_url", task_url_default)
 
-    template = textwrap.dedent(
-        f"""\
+    template = (
+        textwrap.dedent(
+            f"""\
         # Crafter online RL training configuration (research local copy)
 
         [model]
@@ -495,7 +578,9 @@ def _create_new_config(env: DemoEnv) -> str:
         [services]
         task_url = \"{services_task_url}\"
         """
-    ).strip() + "\n"
+        ).strip()
+        + "\n"
+    )
 
     with open(destination, "w", encoding="utf-8") as fh:
         fh.write(template)
@@ -514,7 +599,11 @@ def _select_or_create_config(explicit: str | None, env: DemoEnv) -> str:
     discovered = _find_vllm_tomls(search_root)
 
     extras: list[Path] = []
-    packaged = Path(os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "demo_task_apps", "math", "config.toml")))
+    packaged = Path(
+        os.path.abspath(
+            os.path.join(os.path.dirname(__file__), "..", "demo_task_apps", "math", "config.toml")
+        )
+    )
     extras.append(packaged)
     home_cfg = Path(os.path.expanduser("~/.synth-ai/demo_config.toml"))
     extras.append(home_cfg)
@@ -560,29 +649,36 @@ def _ensure_task_app_ready(env: DemoEnv, synth_key: str, *, label: str) -> DemoE
 
     env_key = (env.env_api_key or "").strip()
     if not env_key:
-        raise RuntimeError(f"[{label}] ENVIRONMENT_API_KEY missing. Run `uvx synth-ai rl_demo deploy` first.")
+        raise RuntimeError(
+            f"[{label}] ENVIRONMENT_API_KEY missing. Run `uvx synth-ai rl_demo deploy` first."
+        )
 
     task_url = env.task_app_base_url
     if not task_url or not _is_modal_public_url(task_url):
         resolved = ""
         if env.task_app_name:
             try:
-                choice = input(
-                    f"Resolve URL from Modal for app '{env.task_app_name}'? [Y/n]: "
-                ).strip().lower() or "y"
+                choice = (
+                    input(f"Resolve URL from Modal for app '{env.task_app_name}'? [Y/n]: ")
+                    .strip()
+                    .lower()
+                    or "y"
+                )
             except Exception:
                 choice = "y"
             if choice.startswith("y"):
-                code, out = _popen_capture([
-                    "uv",
-                    "run",
-                    "python",
-                    "-m",
-                    "modal",
-                    "app",
-                    "url",
-                    env.task_app_name,
-                ])
+                code, out = _popen_capture(
+                    [
+                        "uv",
+                        "run",
+                        "python",
+                        "-m",
+                        "modal",
+                        "app",
+                        "url",
+                        env.task_app_name,
+                    ]
+                )
                 if code == 0 and out:
                     for tok in out.split():
                         if _is_modal_public_url(tok):
@@ -591,7 +687,9 @@ def _ensure_task_app_ready(env: DemoEnv, synth_key: str, *, label: str) -> DemoE
         if not resolved:
             print(f"[{label}] Task app URL not configured or not a valid Modal public URL.")
             print("Examples: https://<app-name>-fastapi-app.modal.run")
-            entered = input("Enter Task App base URL (must contain '.modal.run'), or press Enter to abort: ").strip()
+            entered = input(
+                "Enter Task App base URL (must contain '.modal.run'), or press Enter to abort: "
+            ).strip()
             if not entered or not _is_modal_public_url(entered):
                 raise RuntimeError(f"[{label}] Valid Task App URL is required.")
             task_url = entered.rstrip("/")
@@ -608,11 +706,13 @@ def _ensure_task_app_ready(env: DemoEnv, synth_key: str, *, label: str) -> DemoE
         demo_core.persist_task_url(task_url, name=app_name)
 
     demo_core.persist_task_url(task_url, name=app_name)
-    demo_core.persist_dotenv_values({
-        "TASK_APP_BASE_URL": task_url,
-        "TASK_APP_NAME": app_name,
-        "TASK_APP_SECRET_NAME": DEFAULT_TASK_APP_SECRET_NAME,
-    })
+    demo_core.persist_dotenv_values(
+        {
+            "TASK_APP_BASE_URL": task_url,
+            "TASK_APP_NAME": app_name,
+            "TASK_APP_SECRET_NAME": DEFAULT_TASK_APP_SECRET_NAME,
+        }
+    )
 
     if synth_key:
         os.environ["SYNTH_API_KEY"] = synth_key
@@ -621,7 +721,6 @@ def _ensure_task_app_ready(env: DemoEnv, synth_key: str, *, label: str) -> DemoE
     if openai_key:
         os.environ["OPENAI_API_KEY"] = openai_key
 
-    rollout_url = task_url.rstrip("/") + "/health/rollout"
     print(f"[{label}] Verifying rollout health:")
     try:
         ek = (env_key or "").strip()
@@ -636,7 +735,6 @@ def _ensure_task_app_ready(env: DemoEnv, synth_key: str, *, label: str) -> DemoE
         print(f"[{label}] GET", h)
         rc, body = _http("GET", h, headers={"X-API-Key": env_key})
         if rc == 200:
-            rollout_url = h
             break
     print(f"[{label}] status: {rc}")
     try:
@@ -648,10 +746,8 @@ def _ensure_task_app_ready(env: DemoEnv, synth_key: str, *, label: str) -> DemoE
     print(f"[{label}] body:", preview)
     if rc != 200:
         print(f"[{label}] Warning: rollout health check failed ({rc}). Response: {body}")
-        try:
+        with contextlib.suppress(Exception):
             print(f"[{label}] Sent header X-API-Key → {_key_preview(env_key, 'X-API-Key')}")
-        except Exception:
-            pass
     else:
         print(f"[{label}] Task app rollout health check OK.")
 
@@ -666,7 +762,15 @@ def _ensure_task_app_ready(env: DemoEnv, synth_key: str, *, label: str) -> DemoE
     return updated_env
 
 
-def cmd_deploy(args: argparse.Namespace) -> int:
+def deploy(
+    local: bool = False, app: str | None = None, name: str | None = None, script: str | None = None
+) -> int:
+    # Change to demo directory if stored
+    demo_dir = demo_core.load_demo_dir()
+    if demo_dir and os.path.isdir(demo_dir):
+        os.chdir(demo_dir)
+        print(f"Using demo directory: {demo_dir}")
+
     env = demo_core.load_env()
     os.environ["TASK_APP_SECRET_NAME"] = DEFAULT_TASK_APP_SECRET_NAME
     cwd_env_path = os.path.join(os.getcwd(), ".env")
@@ -674,21 +778,32 @@ def cmd_deploy(args: argparse.Namespace) -> int:
     url = ""
     app_name = env.task_app_name or ""
     try:
-        if args.local:
+        if local:
             print("Starting local Task App…")
             import subprocess
-            subprocess.Popen([sys.executable, "-c", "from synth_ai.demos.demo_task_apps.math.app import run; run()"],
-                             stdout=sys.stdout, stderr=sys.stderr)
+
+            subprocess.Popen(
+                [
+                    sys.executable,
+                    "-c",
+                    "from synth_ai.demos.demo_task_apps.math.app import run; run()",
+                ],
+                env=get_subprocess_env(),
+                stdout=sys.stdout,
+                stderr=sys.stderr,
+            )
             target = "http://127.0.0.1:8080"
             app_name = ""
             for _ in range(30):
-                if demo_core.assert_http_ok(target + "/health", method="GET") or demo_core.assert_http_ok(target, method="GET"):
+                if demo_core.assert_http_ok(
+                    target + "/health", method="GET"
+                ) or demo_core.assert_http_ok(target, method="GET"):
                     url = target
                     break
                 time.sleep(1)
         else:
             # Auto-detect app path if not supplied; prompt interactively from discovered ASGI apps
-            app_path = os.path.abspath(args.app) if args.app else None
+            app_path = os.path.abspath(app) if app else None
             if not app_path or not os.path.isfile(app_path):
                 # First pass: look for known common filenames
                 candidates = [
@@ -707,7 +822,9 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                             rel = os.path.relpath(str(pth), os.getcwd())
                             print(f"  [{idx}] {rel}")
                         try:
-                            sel = input(f"Enter choice [1-{len(found)}] (default 1): ").strip() or "1"
+                            sel = (
+                                input(f"Enter choice [1-{len(found)}] (default 1): ").strip() or "1"
+                            )
                         except Exception:
                             sel = "1"
                         try:
@@ -716,12 +833,13 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                             choice = 1
                         choice = max(1, min(choice, len(found)))
                         app_path = str(found[choice - 1].resolve())
-            if not app_path and args.script:
+            if not app_path and script:
                 # Legacy script fallback if user supplied --script explicitly
                 from synth_ai.demos.demo_task_apps.math.deploy_modal import deploy as modal_deploy
-                url = modal_deploy(script_path=args.script, env_api_key=env.env_api_key)
-                if args.name:
-                    app_name = args.name
+
+                url = modal_deploy(script_path=script, env_api_key=env.env_api_key)
+                if name:
+                    app_name = name
             else:
                 if not app_path:
                     entered = input("Path to Modal app.py (e.g., ./task_app.py): ").strip()
@@ -732,7 +850,7 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                     raise FileNotFoundError(f"App file not found: {app_path}")
                 # Surface the app path before asking for the name
                 print(f"Using task app: {app_path}")
-                existing_name = (args.name or env.task_app_name or "").strip()
+                existing_name = (name or env.task_app_name or "").strip()
                 if not existing_name:
                     existing_name = f"synth-{os.path.splitext(os.path.basename(app_path))[0]}"
                 suggested_name = existing_name
@@ -750,16 +868,19 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                 env_key: str | None = existing_env_key or None
                 if existing_env_key:
                     try:
-                        reuse_choice = input(
-                            "Use existing ENVIRONMENT_API_KEY from state/.env? [Y/n]: "
-                        ).strip().lower() or "y"
+                        reuse_choice = (
+                            input("Use existing ENVIRONMENT_API_KEY from state/.env? [Y/n]: ")
+                            .strip()
+                            .lower()
+                            or "y"
+                        )
                     except Exception:
                         reuse_choice = "y"
                     if not reuse_choice.startswith("y"):
                         env_key = None
 
                 if env_key is None:
-                    from synth_ai.rl.secrets import mint_environment_api_key
+                    from synth_ai.learning.rl.secrets import mint_environment_api_key
 
                     env_key = mint_environment_api_key()
                     demo_core.persist_env_api_key(env_key)
@@ -770,35 +891,50 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                     print("[deploy] Minted new ENVIRONMENT_API_KEY")
                 elif env_key:
                     os.environ["ENVIRONMENT_API_KEY"] = env_key
-                
+
                 # Optionally upload the new key to the backend using sealed box helper
                 backend_base = (env.dev_backend_url or "").rstrip("/")
-                synth_key = (env.synth_api_key or os.environ.get("SYNTH_API_KEY") or local_env.get("SYNTH_API_KEY") or "").strip()
+                synth_key = (
+                    env.synth_api_key
+                    or os.environ.get("SYNTH_API_KEY")
+                    or local_env.get("SYNTH_API_KEY")
+                    or ""
+                ).strip()
                 if backend_base and synth_key:
-                        # Pass a base WITHOUT trailing /api to setup_environment_api_key,
-                        # since it appends /api/v1/... internally.
-                        non_api_base = backend_base[:-4] if backend_base.endswith("/api") else backend_base
+                    # Pass a base WITHOUT trailing /api to setup_environment_api_key,
+                    # since it appends /api/v1/... internally.
+                    non_api_base = (
+                        backend_base[:-4] if backend_base.endswith("/api") else backend_base
+                    )
+                    try:
+                        choice = (
+                            input(f"Upload ENVIRONMENT_API_KEY to backend {non_api_base}? [Y/n]: ")
+                            .strip()
+                            .lower()
+                            or "y"
+                        )
+                    except Exception:
+                        choice = "y"
+                    if choice.startswith("y"):
                         try:
-                            choice = input(
-                                f"Upload ENVIRONMENT_API_KEY to backend {non_api_base}? [Y/n]: "
-                            ).strip().lower() or "y"
-                        except Exception:
-                            choice = "y"
-                        if choice.startswith("y"):
-                            try:
-                                print(f"[deploy] Uploading ENVIRONMENT_API_KEY to {non_api_base} …")
-                                from synth_ai.rl.env_keys import setup_environment_api_key
-
-                                setup_environment_api_key(non_api_base, synth_key, token=env_key)
-                                print("[deploy] Backend sealed-box upload complete.")
-                            except Exception as upload_err:
-                                print(f"[deploy] Failed to upload ENVIRONMENT_API_KEY: {upload_err}")
-                                print(
-                                    "Hint: run `uvx python -c \"from synth_ai.rl.env_keys import setup_environment_api_key as s;"
-                                    " s('<backend>', '<synth_api_key>')\"` once the backend is reachable."
-                                )
-
-                synth_key = (env.synth_api_key or os.environ.get("SYNTH_API_KEY") or local_env.get("SYNTH_API_KEY") or "").strip()
+                            print(f"[deploy] Uploading ENVIRONMENT_API_KEY to {non_api_base} …")
+                            from synth_ai.learning.rl.env_keys import setup_environment_api_key
+
+                            setup_environment_api_key(non_api_base, synth_key, token=env_key)
+                            print("[deploy] Backend sealed-box upload complete.")
+                        except Exception as upload_err:
+                            print(f"[deploy] Failed to upload ENVIRONMENT_API_KEY: {upload_err}")
+                            print(
+                                'Hint: run `uvx python -c "from synth_ai.learning.rl.env_keys import setup_environment_api_key as s;'
+                                " s('<backend>', '<synth_api_key>')\"` once the backend is reachable."
+                            )
+
+                synth_key = (
+                    env.synth_api_key
+                    or os.environ.get("SYNTH_API_KEY")
+                    or local_env.get("SYNTH_API_KEY")
+                    or ""
+                ).strip()
                 if not synth_key:
                     synth_key = input("Enter SYNTH_API_KEY for deployment (required): ").strip()
                     if not synth_key:
@@ -809,7 +945,9 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                     env.synth_api_key = synth_key
                 os.environ["SYNTH_API_KEY"] = synth_key
 
-                openai_key = (os.environ.get("OPENAI_API_KEY") or local_env.get("OPENAI_API_KEY") or "").strip()
+                openai_key = (
+                    os.environ.get("OPENAI_API_KEY") or local_env.get("OPENAI_API_KEY") or ""
+                ).strip()
                 if not openai_key:
                     openai_key = input(
                         "Enter your OpenAI API key, found at https://platform.openai.com/api-keys\n> "
@@ -821,8 +959,20 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                     local_env["OPENAI_API_KEY"] = openai_key
                 os.environ["OPENAI_API_KEY"] = openai_key
 
-                deploy_cmd = ["uv", "run", "python", "-m", "modal", "deploy", "--name", name_in, app_path]
-                print("\nStreaming Modal build/deploy logs (this can take several minutes on first run)…\n")
+                deploy_cmd = [
+                    "uv",
+                    "run",
+                    "python",
+                    "-m",
+                    "modal",
+                    "deploy",
+                    "--name",
+                    name_in,
+                    app_path,
+                ]
+                print(
+                    "\nStreaming Modal build/deploy logs (this can take several minutes on first run)…\n"
+                )
                 code, deploy_logs = _popen_stream_capture(deploy_cmd)
                 if code != 0:
                     raise RuntimeError(f"modal deploy failed (exit {code})")
@@ -830,6 +980,7 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                 if not url:
                     try:
                         import re as _re
+
                         m_all = _re.findall(r"https?://[^\s]+\.modal\.run", deploy_logs or "")
                         if m_all:
                             url = m_all[-1].strip().rstrip("/")
@@ -844,7 +995,9 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                             break
                 # Fallback: try reading recent Modal logs for the app to find a URL line
                 if not url:
-                    code3, out3 = _popen_capture(["uv", "run", "python", "-m", "modal", "app", "list"])
+                    code3, out3 = _popen_capture(
+                        ["uv", "run", "python", "-m", "modal", "app", "list"]
+                    )
                     if code3 == 0 and out3:
                         for line in out3.splitlines():
                             if name_in in line:
@@ -857,7 +1010,9 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                 # Prompt user if still no valid URL
                 if not url:
                     print("\nCould not auto-detect a public Modal URL for the app.")
-                    entered = input("Enter the Modal public URL (must contain '.modal.run'), or press Enter to abort: ").strip()
+                    entered = input(
+                        "Enter the Modal public URL (must contain '.modal.run'), or press Enter to abort: "
+                    ).strip()
                     if entered and _is_modal_public_url(entered):
                         url = entered.rstrip("/")
                 if not url:
@@ -885,8 +1040,9 @@ def cmd_deploy(args: argparse.Namespace) -> int:
         print(f"Deploy error: {e}")
         return 2
 
-
-    print("`rl_demo configure` prepares environment and secrets; `synth-ai run` now handles launches.")
+    print(
+        "`rl_demo configure` prepares environment and secrets; `synth-ai run` now handles launches."
+    )
     env = demo_core.load_env()
     synth_key = (env.synth_api_key or "").strip()
     if not synth_key:
@@ -919,43 +1075,65 @@ def cmd_deploy(args: argparse.Namespace) -> int:
 
 
 def _ensure_modal_installed() -> None:
-    """Install the modal package if it is not already available."""
+    """Install the modal package if it is not already available and check authentication."""
 
+    # Check if modal is installed
+    modal_installed = False
     try:
         import importlib.util as _iu
 
         if _iu.find_spec("modal") is not None:
-            print("modal package found")
-            return
+            modal_installed = True
     except Exception:
         pass
 
-    print("modal not found; installing…")
-    try:
-        if shutil.which("uv"):
-            code, out = _popen_capture(["uv", "pip", "install", "modal>=1.1.4"])
-        else:
-            code, out = _popen_capture([sys.executable, "-m", "pip", "install", "modal>=1.1.4"])
-        if code != 0:
-            print(out)
-            print("Failed to install modal; continuing may fail.")
-        else:
-            print("modal installed successfully.")
-    except Exception as exc:
-        print(f"modal install error: {exc}")
+    # Install modal if needed
+    if not modal_installed:
+        print("modal not found; installing…")
+        try:
+            if shutil.which("uv"):
+                code, out = _popen_capture(["uv", "pip", "install", "modal>=1.1.4"])
+            else:
+                code, out = _popen_capture([sys.executable, "-m", "pip", "install", "modal>=1.1.4"])
+            if code != 0:
+                print(out)
+                print("Failed to install modal; continuing may fail.")
+                return
+            else:
+                print("✓ modal installed successfully")
+                modal_installed = True
+        except Exception as exc:
+            print(f"modal install error: {exc}")
+            return
 
-    try:
-        import importlib.util as _iu
+    # Verify modal is importable
+    if modal_installed:
+        try:
+            import importlib.util as _iu
 
-        if _iu.find_spec("modal") is None:
-            print("Warning: modal is still not importable after install attempt.")
-        else:
-            print("modal package ready")
-    except Exception:
-        print("Warning: unable to verify modal installation.")
+            if _iu.find_spec("modal") is None:
+                print("Warning: modal is still not importable after install attempt.")
+                return
+        except Exception:
+            print("Warning: unable to verify modal installation.")
+            return
+
+    # Check modal authentication status
+    auth_ok, auth_msg = demo_core.modal_auth_status()
+    if auth_ok:
+        print(f"✓ Modal authenticated: {auth_msg}")
+    else:
+        print("\n⚠️  Modal authentication required")
+        print(f"   Status: {auth_msg}")
+        print("\n   To authenticate Modal, run:")
+        print("     modal setup")
+        print("\n   Or set environment variables:")
+        print("     export MODAL_TOKEN_ID=your-token-id")
+        print("     export MODAL_TOKEN_SECRET=your-token-secret")
+        print("\n   You can deploy later after authenticating.\n")
 
 
-def cmd_init(args: argparse.Namespace) -> int:
+def init(template: str | None = None, dest: str | None = None, force: bool = False) -> int:
     """Materialise a demo task app template into the current directory."""
 
     templates = list(list_demo_templates())
@@ -964,47 +1142,101 @@ def cmd_init(args: argparse.Namespace) -> int:
         return 1
 
     selected: DemoTemplate | None = None
-    if args.template:
-        selected = get_demo_template(args.template)
+    if template:
+        selected = get_demo_template(template)
         if selected is None:
             available = ", ".join(t.template_id for t in templates)
-            print(f"Unknown template '{args.template}'. Available: {available}")
+            print(f"Unknown template '{template}'. Available: {available}")
             return 1
     else:
-        print("Select a demo template:" + "\n")
-        for idx, template in enumerate(templates, start=1):
-            print(f"  [{idx}] {template.name} ({template.template_id})")
-            print(f"      {template.description}")
-        try:
-            choice_raw = input(f"Enter choice [1-{len(templates)}] (default 1): ").strip() or "1"
-        except Exception:
-            choice_raw = "1"
-        if not choice_raw.isdigit():
-            print("Selection must be a number.")
-            return 1
-        choice_idx = int(choice_raw)
-        if not 1 <= choice_idx <= len(templates):
-            print("Selection out of range.")
-            return 1
-        selected = templates[choice_idx - 1]
+        if force:
+            selected = templates[0]
+            print(
+                f"Using default template: {selected.name} ({selected.template_id}) "
+                f"(pass --template to choose another)"
+            )
+        else:
+            print("Select a demo template:" + "\n")
+            for idx, tpl in enumerate(templates, start=1):
+                print(f"  [{idx}] {tpl.name} ({tpl.template_id})")
+                print(f"      {tpl.description}")
+            try:
+                choice_raw = input(f"Enter choice [1-{len(templates)}] (default 1): ").strip() or "1"
+            except Exception:
+                choice_raw = "1"
+            if not choice_raw.isdigit():
+                print("Selection must be a number.")
+                return 1
+            choice_idx = int(choice_raw)
+            if not 1 <= choice_idx <= len(templates):
+                print("Selection out of range.")
+                return 1
+            selected = templates[choice_idx - 1]
 
     assert selected is not None
 
     default_subdir = selected.default_subdir or selected.template_id
-    default_dest = Path(args.dest).expanduser().resolve() if args.dest else (Path.cwd() / default_subdir).resolve()
-    try:
-        dest_input = input(f"Destination directory [{default_dest}]: ").strip()
-    except Exception:
+
+    # Check if default destination is already occupied and switch to local_demos/ if needed
+    if dest:
+        default_dest = Path(dest).expanduser().resolve()
+    else:
+        primary_dest = Path.cwd() / default_subdir
+        if primary_dest.exists() and any(primary_dest.iterdir()):
+            # Switch to local_demos/ automatically if primary location is occupied
+            default_dest = (Path.cwd() / "local_demos" / default_subdir).resolve()
+        else:
+            default_dest = primary_dest.resolve()
+
+    if force:
         dest_input = ""
+    else:
+        try:
+            dest_input = input(f"Destination directory [{default_dest}]: ").strip()
+        except Exception:
+            dest_input = ""
     destination = Path(dest_input).expanduser().resolve() if dest_input else default_dest
 
+    # Track whether we should skip individual file prompts (if we already cleared the directory)
+    directory_cleared = False
+
     if destination.exists():
         if destination.is_file():
             print(f"Destination {destination} is a file. Provide a directory path.")
             return 1
-        if not args.force and any(destination.iterdir()):
-            print(f"Destination {destination} is not empty. Use --force or choose another directory.")
-            return 1
+        if any(destination.iterdir()):
+            if force:
+                response = "y"
+            else:
+                try:
+                    response = (
+                        input(f"Destination {destination} is not empty. Overwrite? [y/N]: ")
+                        .strip()
+                        .lower()
+                    )
+                except (EOFError, KeyboardInterrupt):
+                    print("\nCancelled.")
+                    return 1
+            if response not in ("y", "yes"):
+                print("Cancelled. Choose another directory or delete the existing one.")
+                return 1
+            # User agreed to overwrite - clear the entire directory including hidden files
+            print(f"Clearing {destination}...")
+            try:
+                # Remove all contents including hidden files (.env, .git, etc.)
+                shutil.rmtree(destination)
+            except Exception as e:
+                print(f"Error clearing directory: {e}")
+                print("Please manually remove the directory and try again.")
+                return 1
+            # Recreate empty directory
+            destination.mkdir(parents=True, exist_ok=True)
+            # Verify it's actually empty
+            if any(destination.iterdir()):
+                print(f"Warning: Directory {destination} still contains files after clearing.")
+                print("Some files may not have been removed. Please check manually.")
+                return 1
+            directory_cleared = True
     else:
         destination.mkdir(parents=True, exist_ok=True)
 
@@ -1018,29 +1250,95 @@ def cmd_init(args: argparse.Namespace) -> int:
                 print(f"Template source missing: {src_path}")
                 return 1
             dest_path = (destination / spec.destination).resolve()
-            dest_path.parent.mkdir(parents=True, exist_ok=True)
-            if dest_path.exists() and not args.force:
-                print(f"Refusing to overwrite existing file: {dest_path} (use --force)")
-                return 1
-            shutil.copy2(src_path, dest_path)
-            if spec.make_executable:
-                try:
-                    st = os.stat(dest_path)
-                    os.chmod(dest_path, st.st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
-                except Exception:
-                    pass
+
+            # Handle directory copying
+            if src_path.is_dir():
+                if dest_path.exists() and not directory_cleared:
+                    if force:
+                        response = "y"
+                    else:
+                        try:
+                            response = (
+                                input(f"Directory {dest_path.name} exists. Overwrite? [y/N]: ")
+                                .strip()
+                                .lower()
+                            )
+                        except (EOFError, KeyboardInterrupt):
+                            print("\nCancelled.")
+                            return 1
+                    if response not in ("y", "yes"):
+                        print(f"Skipping {dest_path.name}")
+                        continue
+                    shutil.rmtree(dest_path)
+                elif dest_path.exists() and directory_cleared:
+                    shutil.rmtree(dest_path)
+                shutil.copytree(src_path, dest_path)
+            else:
+                # Handle file copying
+                dest_path.parent.mkdir(parents=True, exist_ok=True)
+                if dest_path.exists() and not directory_cleared:
+                    if force:
+                        response = "y"
+                    else:
+                        try:
+                            response = (
+                                input(f"File {dest_path.name} exists. Overwrite? [y/N]: ")
+                                .strip()
+                                .lower()
+                            )
+                        except (EOFError, KeyboardInterrupt):
+                            print("\nCancelled.")
+                            return 1
+                    if response not in ("y", "yes"):
+                        print(f"Skipping {dest_path.name}")
+                        continue
+                shutil.copy2(src_path, dest_path)
+                if spec.make_executable:
+                    try:
+                        st = os.stat(dest_path)
+                        os.chmod(dest_path, st.st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+                    except Exception:
+                        pass
 
         if selected.env_lines:
             env_path = destination / ".env"
-            if not env_path.exists() or args.force:
+            should_write = True
+            if env_path.exists() and not directory_cleared:
+                if force:
+                    response = "y"
+                else:
+                    try:
+                        response = input("File .env exists. Overwrite? [y/N]: ").strip().lower()
+                    except (EOFError, KeyboardInterrupt):
+                        print("\nCancelled.")
+                        return 1
+                should_write = response in ("y", "yes")
+            if should_write:
                 _write_text(env_path, "\n".join(selected.env_lines) + "\n")
+            elif not directory_cleared:
+                print("Skipping .env")
 
         config_src = selected.config_source_path()
         if config_src and config_src.exists():
             cfg_dst = (destination / selected.config_destination).resolve()
-            if not cfg_dst.exists() or args.force:
+            should_copy = True
+            if cfg_dst.exists() and not directory_cleared:
+                if force:
+                    response = "y"
+                else:
+                    try:
+                        response = (
+                            input(f"File {cfg_dst.name} exists. Overwrite? [y/N]: ").strip().lower()
+                        )
+                    except (EOFError, KeyboardInterrupt):
+                        print("\nCancelled.")
+                        return 1
+                should_copy = response in ("y", "yes")
+            if should_copy:
                 cfg_dst.parent.mkdir(parents=True, exist_ok=True)
                 shutil.copy2(config_src, cfg_dst)
+            elif not directory_cleared:
+                print(f"Skipping {cfg_dst.name}")
 
         if selected.post_copy is not None:
             try:
@@ -1049,6 +1347,14 @@ def cmd_init(args: argparse.Namespace) -> int:
                 print(f"Post-processing failed: {post_exc}")
                 return 1
 
+        # Store demo directory for subsequent commands
+        demo_core.persist_demo_dir(str(destination))
+
+        # Store .env path if it was created
+        env_file = destination / ".env"
+        if env_file.exists():
+            demo_core.persist_env_file_path(str(env_file))
+
         print(f"Demo template '{selected.name}' materialised at {destination}.")
         print("Files created:")
         for spec in selected.iter_copy_specs():
@@ -1057,6 +1363,7 @@ def cmd_init(args: argparse.Namespace) -> int:
             print("  - .env")
         if selected.config_source_path():
             print(f"  - {selected.config_destination}")
+        print("\nDemo directory stored. Subsequent commands will use this directory automatically.")
         print("Review the files, edit .env, and run any provided deploy scripts when ready.")
         return 0
     except KeyboardInterrupt:
@@ -1067,8 +1374,14 @@ def cmd_init(args: argparse.Namespace) -> int:
         return 1
 
 
-def _http(method: str, url: str, headers: Dict[str, str] | None = None, body: Dict[str, Any] | None = None) -> tuple[int, Dict[str, Any] | str]:
-    import urllib.request, urllib.error, json as _json, ssl
+def _http(
+    method: str, url: str, headers: dict[str, str] | None = None, body: dict[str, Any] | None = None
+) -> tuple[int, dict[str, Any] | str]:
+    import json as _json
+    import ssl
+    import urllib.error
+    import urllib.request
+
     data = None
     if body is not None:
         data = _json.dumps(body).encode("utf-8")
@@ -1105,10 +1418,23 @@ def _write_text(path: str, content: str) -> None:
 # Note: `prepare` command has been removed; configuration now prepares TOML
 
 
-def cmd_run(args: argparse.Namespace) -> int:
+def run(
+    config: str | None = None,
+    batch_size: int | None = None,
+    group_size: int | None = None,
+    model: str | None = None,
+    timeout: int = 600,
+    dry_run: bool = False,
+) -> int:
+    # Change to demo directory if stored
+    demo_dir = demo_core.load_demo_dir()
+    if demo_dir and os.path.isdir(demo_dir):
+        os.chdir(demo_dir)
+        print(f"Using demo directory: {demo_dir}")
+
     env = demo_core.load_env()
     cwd_env_path = os.path.join(os.getcwd(), ".env")
-    local_env = demo_core.load_dotenv_file(cwd_env_path)
+    demo_core.load_dotenv_file(cwd_env_path)
 
     synth_key = (env.synth_api_key or "").strip()
     if not synth_key:
@@ -1140,7 +1466,7 @@ def cmd_run(args: argparse.Namespace) -> int:
     import tomllib
 
     try:
-        cfg_path = _select_or_create_config(getattr(args, "config", None), env)
+        cfg_path = _select_or_create_config(config, env)
     except FileNotFoundError as exc:
         print(exc)
         return 1
@@ -1148,7 +1474,11 @@ def cmd_run(args: argparse.Namespace) -> int:
     # Detect monorepo launcher and delegate if available (aligns with run_clustered.sh which works)
     launcher = "/Users/joshpurtell/Documents/GitHub/monorepo/tests/applications/math/rl/start_math_clustered.py"
     if os.path.isfile(launcher):
-        backend_base = env.dev_backend_url[:-4] if env.dev_backend_url.endswith("/api") else env.dev_backend_url
+        backend_base = (
+            env.dev_backend_url[:-4]
+            if env.dev_backend_url.endswith("/api")
+            else env.dev_backend_url
+        )
         run_env = os.environ.copy()
         run_env["BACKEND_URL"] = backend_base
         run_env["SYNTH_API_KEY"] = env.synth_api_key
@@ -1158,12 +1488,12 @@ def cmd_run(args: argparse.Namespace) -> int:
         # Optional: TRAINER_START_URL passthrough if already set in environment
         run_env["TRAINER_START_URL"] = run_env.get("TRAINER_START_URL", "")
         # Forward convenience knobs
-        if args.batch_size is not None:
-            run_env["RL_BATCH_SIZE"] = str(int(args.batch_size))
-        if args.group_size is not None:
-            run_env["RL_GROUP_SIZE"] = str(int(args.group_size))
-        if args.model:
-            run_env["RL_MODEL"] = args.model
+        if batch_size is not None:
+            run_env["RL_BATCH_SIZE"] = str(int(batch_size))
+        if group_size is not None:
+            run_env["RL_GROUP_SIZE"] = str(int(group_size))
+        if model:
+            run_env["RL_MODEL"] = model
         cmd = ["uv", "run", "python", launcher]
         print(f"Launching monorepo clustered runner: {' '.join(cmd)}")
         code = _popen_stream(cmd, env=run_env)
@@ -1181,30 +1511,30 @@ def cmd_run(args: argparse.Namespace) -> int:
                 print(f"  {_key_preview(sk, 'SYNTH_API_KEY')}")
             if ek:
                 print(f"  {_key_preview(ek, 'ENVIRONMENT_API_KEY')}")
-            print("Ensure the ENVIRONMENT_API_KEY you deployed with matches the task app and remains exported.")
+            print(
+                "Ensure the ENVIRONMENT_API_KEY you deployed with matches the task app and remains exported."
+            )
         return code
 
     # Fallback: legacy jobs API flow
     with open(cfg_path, "rb") as fh:
         inline_cfg = tomllib.load(fh)
-    with open(cfg_path, "r") as fh2:
+    with open(cfg_path) as fh2:
         toml_text = fh2.read()
-    if args.batch_size is not None:
-        inline_cfg.setdefault("training", {})["batch_size"] = int(args.batch_size)
-    if args.group_size is not None:
-        inline_cfg.setdefault("training", {})["group_size"] = int(args.group_size)
-    model_name = args.model or (inline_cfg.get("model", {}) or {}).get("name", "Qwen/Qwen3-0.6B")
+    if batch_size is not None:
+        inline_cfg.setdefault("training", {})["batch_size"] = int(batch_size)
+    if group_size is not None:
+        inline_cfg.setdefault("training", {})["group_size"] = int(group_size)
+    model_name = model or (inline_cfg.get("model", {}) or {}).get("name", "Qwen/Qwen3-0.6B")
     api = env.dev_backend_url.rstrip("/") + ("" if env.dev_backend_url.endswith("/api") else "/api")
     # Print backend and key preview before request for clearer diagnostics
     try:
         sk = (env.synth_api_key or "").strip()
-        sk_len = len(sk)
-        sk_tail = sk[-5:] if sk_len >= 5 else sk
         print(f"[run] Backend API: {api}")
         print(f"[run] {_key_preview(sk, 'SYNTH_API_KEY')}")
     except Exception:
         pass
-    data_fragment: Dict[str, Any] = {
+    data_fragment: dict[str, Any] = {
         "model": model_name,
         "endpoint_base_url": env.task_app_base_url,
         "config": inline_cfg,
@@ -1222,23 +1552,28 @@ def cmd_run(args: argparse.Namespace) -> int:
         if inline_cfg["compute"].get("gpu_type"):
             compute["gpu_type"] = str(inline_cfg["compute"]["gpu_type"]).upper()
         if inline_cfg["compute"].get("gpu_count"):
-            compute["gpu_count"] = int(inline_cfg["compute"]["gpu_count"]) 
+            compute["gpu_count"] = int(inline_cfg["compute"]["gpu_count"])
     if not compute:
         topo = inline_cfg.get("topology") or {}
         gshape = str(topo.get("gpu_type") or "")
         if ":" in gshape:
             t, c = gshape.split(":", 1)
             compute = {"gpu_type": t.upper(), "gpu_count": int(c)}
-    body: Dict[str, Any] = {
+    body: dict[str, Any] = {
         "job_type": "rl",
         "data": data_fragment,
     }
     if compute:
         body["compute"] = compute
-    code, js = _http("POST", api + "/rl/jobs", headers={
-        "Content-Type": "application/json",
-        "Authorization": f"Bearer {env.synth_api_key}",
-    }, body=body)
+    code, js = _http(
+        "POST",
+        api + "/rl/jobs",
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {env.synth_api_key}",
+        },
+        body=body,
+    )
     if code not in (200, 201) or not isinstance(js, dict):
         print("Job create failed:", code)
         print(f"Backend: {api}")
@@ -1276,12 +1611,14 @@ def cmd_run(args: argparse.Namespace) -> int:
                 try:
                     sent_key = detail.get("sent_key")
                     if isinstance(sent_key, str):
-                        print(f"[run] Backend detail.sent_key {_key_preview(sent_key, 'detail.sent_key')}")
+                        print(
+                            f"[run] Backend detail.sent_key {_key_preview(sent_key, 'detail.sent_key')}"
+                        )
                 except Exception:
                     pass
                 try:
                     sent_keys = detail.get("sent_keys")
-                    if isinstance(sent_keys, (list, tuple)):
+                    if isinstance(sent_keys, list | tuple):
                         previews = []
                         for idx, val in enumerate(sent_keys):
                             if isinstance(val, str):
@@ -1306,12 +1643,19 @@ def cmd_run(args: argparse.Namespace) -> int:
         # Extra hints for auth failures
         try:
             sk = (env.synth_api_key or "").strip()
-            if int(code) == 401 or (isinstance(js, dict) and any(isinstance(v, str) and "Invalid API key" in v for v in js.values())):
+            if int(code) == 401 or (
+                isinstance(js, dict)
+                and any(isinstance(v, str) and "Invalid API key" in v for v in js.values())
+            ):
                 base_url = env.dev_backend_url
-                print("Hint: HTTP 401 Unauthorized from backend. Verify SYNTH_API_KEY for:", base_url)
+                print(
+                    "Hint: HTTP 401 Unauthorized from backend. Verify SYNTH_API_KEY for:", base_url
+                )
                 if sk:
                     print(f"  {_key_preview(sk, 'SYNTH_API_KEY')}")
-                print("Ensure the ENVIRONMENT_API_KEY and OPENAI_API_KEY used for deployment remain valid.")
+                print(
+                    "Ensure the ENVIRONMENT_API_KEY and OPENAI_API_KEY used for deployment remain valid."
+                )
         except Exception:
             pass
         return 2
@@ -1363,9 +1707,7 @@ def cmd_run(args: argparse.Namespace) -> int:
                     "rl.performance.metrics",
                 ):
                     print(f"[{seq}] {typ}: {msg}")
-        mc, mj = _http(
-            "GET", api + f"/learning/jobs/{job_id}/metrics?after_step=-1&limit=50"
-        )
+        mc, mj = _http("GET", api + f"/learning/jobs/{job_id}/metrics?after_step=-1&limit=50")
         if mc == 200 and isinstance(mj, dict):
             pts = mj.get("points") or []
             for p in pts:
@@ -1373,62 +1715,8 @@ def cmd_run(args: argparse.Namespace) -> int:
                 if name == "eval.reward_mean":
                     print(f"metric eval.reward_mean step={p.get('step')} value={p.get('value')}")
                     break
-        if time.time() - start_t > (args.timeout or 600):
+        if time.time() - start_t > (timeout or 600):
             print("Timeout waiting for terminal state.")
             break
         time.sleep(2)
     return 0
-
-
-def main(argv: list[str] | None = None) -> int:
-    p = argparse.ArgumentParser(prog="synth-ai")
-    sub = p.add_subparsers(dest="cmd")
-
-    def _add_parser(names: list[str], *, configure: Callable[[argparse.ArgumentParser], None]) -> None:
-        for name in names:
-            parser = sub.add_parser(name)
-            configure(parser)
-
-    _add_parser(["rl_demo.setup", "demo.setup"], configure=lambda parser: parser.set_defaults(func=cmd_setup))
-
-    def _init_opts(parser):
-        parser.add_argument("--template", type=str, default=None, help="Template id to instantiate")
-        parser.add_argument("--dest", type=str, default=None, help="Destination directory for files")
-        parser.add_argument("--force", action="store_true", help="Overwrite existing files in destination")
-        parser.set_defaults(func=cmd_init)
-
-    _add_parser(["rl_demo.init", "demo.init"], configure=_init_opts)
-
-    # (prepare command removed)
-
-    def _deploy_opts(parser):
-        parser.add_argument("--local", action="store_true", help="Run local FastAPI instead of Modal deploy")
-        parser.add_argument("--app", type=str, default=None, help="Path to Modal app.py for uv run modal deploy")
-        parser.add_argument("--name", type=str, default=None, help="Modal app name")
-        parser.add_argument("--script", type=str, default=None, help="Path to deploy_task_app.sh (optional legacy)")
-        parser.set_defaults(func=cmd_deploy)
-
-    _add_parser(["rl_demo.deploy", "demo.deploy"], configure=_deploy_opts)
-
-    _add_parser(["rl_demo.configure", "demo.configure"], configure=lambda parser: parser.set_defaults(func=cmd_run))
-
-    def _run_opts(parser):
-        parser.add_argument("--config", type=str, default=None, help="Path to TOML config (skip prompt)")
-        parser.add_argument("--batch-size", type=int, default=None)
-        parser.add_argument("--group-size", type=int, default=None)
-        parser.add_argument("--model", type=str, default=None)
-        parser.add_argument("--timeout", type=int, default=600)
-        parser.add_argument("--dry-run", action="store_true", help="Print request body and exit")
-        parser.set_defaults(func=cmd_run)
-
-    _add_parser(["run", "rl_demo.run", "demo.run"], configure=_run_opts)
-
-    args = p.parse_args(argv)
-    if not hasattr(args, "func"):
-        p.print_help()
-        return 1
-    return int(args.func(args) or 0)
-
-
-if __name__ == "__main__":
-    sys.exit(main())