wafer-cli 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

wafer/cli.py

@@ -18,9 +18,11 @@ Setup:
   config                CLI configuration and local GPU targets
 """
 
+import atexit
 import json
 import os
 import sys
+import time
 from pathlib import Path
 
 import trio
@@ -34,6 +36,98 @@ app = typer.Typer(
     no_args_is_help=True,
 )
 
+# =============================================================================
+# Analytics tracking
+# =============================================================================
+
+# Track command start time for duration calculation
+_command_start_time: float | None = None
+# Track command outcome (defaults to failure, set to success on clean exit)
+_command_outcome: str = "failure"
+
+
+def _get_command_path(ctx: typer.Context) -> tuple[str, str | None]:
+    """Extract command and subcommand from Typer context.
+
+    Returns:
+        Tuple of (command, subcommand). subcommand may be None.
+    """
+    # Build command path from invoked subcommand chain
+    invoked = ctx.invoked_subcommand
+    info_name = ctx.info_name or ""
+
+    # Get parent command if exists
+    parent_cmd = None
+    if ctx.parent and ctx.parent.info_name and ctx.parent.info_name != "wafer":
+        parent_cmd = ctx.parent.info_name
+
+    if parent_cmd:
+        return parent_cmd, info_name
+    return info_name or "unknown", invoked
+
+
+def _mark_command_success() -> None:
+    """Mark the current command as successful.
+
+    Call this at the end of successful command execution.
+    Commands that raise typer.Exit(1) or exceptions will remain marked as failures.
+    """
+    global _command_outcome
+    _command_outcome = "success"
+
+
+@app.callback()
+def main_callback(ctx: typer.Context) -> None:
+    """Initialize analytics and track command execution."""
+    global _command_start_time, _command_outcome
+    _command_start_time = time.time()
+    _command_outcome = "success"  # Default to success, mark failure on exceptions
+
+    # Initialize analytics (lazy import to avoid slowing down --help)
+    from . import analytics
+
+    analytics.init_analytics()
+
+    # Install exception hook to catch SystemExit and mark failures
+    original_excepthook = sys.excepthook
+
+    def custom_excepthook(exc_type, exc_value, exc_traceback):
+        global _command_outcome
+        # Mark as failure if SystemExit with non-zero code, or any other exception
+        if exc_type is SystemExit:
+            exit_code = exc_value.code if hasattr(exc_value, 'code') else 1
+            if exit_code != 0 and exit_code is not None:
+                _command_outcome = "failure"
+        else:
+            _command_outcome = "failure"
+        # Call original excepthook
+        original_excepthook(exc_type, exc_value, exc_traceback)
+
+    sys.excepthook = custom_excepthook
+
+    # Register tracking at exit to capture command outcome
+    def track_on_exit() -> None:
+        command, subcommand = _get_command_path(ctx)
+
+        # Skip tracking for --help and --version
+        if ctx.resilient_parsing:
+            return
+
+        # Calculate duration
+        duration_ms = None
+        if _command_start_time is not None:
+            duration_ms = int((time.time() - _command_start_time) * 1000)
+
+        # Track the command execution with the recorded outcome
+        analytics.track_command(
+            command=command,
+            subcommand=subcommand,
+            outcome=_command_outcome,
+            duration_ms=duration_ms,
+        )
+
+    atexit.register(track_on_exit)
+
 
 # =============================================================================
 # Autocompletion helpers
@@ -57,13 +151,37 @@ config_app = typer.Typer(help="Manage CLI configuration and local GPU targets")
 app.add_typer(config_app, name="config")
 
 # Target management - nested under config
-targets_app = typer.Typer(help="Manage local GPU targets (TOML files)")
+targets_app = typer.Typer(
+    help="""Manage GPU targets for remote evaluation.
+
+Targets define how to access GPUs. Use 'wafer config targets init' to set up:
+
+  wafer config targets init ssh        # Your own GPU via SSH
+  wafer config targets init runpod     # RunPod cloud GPUs (needs WAFER_RUNPOD_API_KEY)
+  wafer config targets init digitalocean  # DigitalOcean AMD GPUs
+
+Then use with: wafer evaluate --target <name> ..."""
+)
 config_app.add_typer(targets_app, name="targets")
 
 # Workspace management (remote API-backed)
-workspaces_app = typer.Typer(help="Manage cloud GPU workspaces")
+workspaces_app = typer.Typer(
+    help="""Manage cloud GPU workspaces for remote development.
+
+Workspaces are on-demand cloud GPU environments. Requires authentication (wafer login).
+
+  wafer workspaces create dev --gpu H100   # Create workspace
+  wafer workspaces exec dev -- python x.py # Run commands
+  wafer workspaces ssh dev                 # Interactive SSH
+  wafer workspaces sync dev ./project      # Sync files
+  wafer workspaces delete dev              # Clean up"""
+)
 app.add_typer(workspaces_app, name="workspaces")
 
+# Billing management
+billing_app = typer.Typer(help="Manage billing, credits, and subscription")
+app.add_typer(billing_app, name="billing")
+
 # Corpus management
 corpus_app = typer.Typer(help="Download and manage GPU documentation")
 app.add_typer(corpus_app, name="corpus")
@@ -124,6 +242,159 @@ app.add_typer(amd_app, name="amd")
 isa_app = typer.Typer(help="ISA analysis for AMD GPU code objects (.co files)")
 amd_app.add_typer(isa_app, name="isa")
 
+# =============================================================================
+# Skill management (wafer skill ...)
+# =============================================================================
+
+skill_app = typer.Typer(help="Manage AI coding assistant skills (Claude Code, Codex)")
+app.add_typer(skill_app, name="skill")
+
+
+@skill_app.command("install")
+def skill_install(
+    target: str = typer.Option(
+        "all",
+        "--target",
+        "-t",
+        help="Target tool: claude, codex, or all",
+    ),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing skill"),
+) -> None:
+    """Install the wafer-guide skill for AI coding assistants.
+
+    Installs the bundled skill to make wafer commands discoverable by
+    Claude Code and/or OpenAI Codex CLI.
+
+    Skills follow the open agent skills specification (agentskills.io).
+
+    Examples:
+        wafer skill install              # Install for both Claude and Codex
+        wafer skill install -t claude    # Install for Claude Code only
+        wafer skill install -t codex     # Install for Codex CLI only
+        wafer skill install --force      # Overwrite existing installation
+    """
+    # Locate bundled skill
+    skill_source = Path(__file__).parent / "skills" / "wafer-guide"
+    if not skill_source.exists():
+        typer.echo("Error: Bundled skill not found. Package may be corrupted.", err=True)
+        raise typer.Exit(1)
+
+    targets_to_install: list[tuple[str, Path]] = []
+
+    if target in ("all", "claude"):
+        targets_to_install.append((
+            "Claude Code",
+            Path.home() / ".claude" / "skills" / "wafer-guide",
+        ))
+    if target in ("all", "codex"):
+        targets_to_install.append(("Codex CLI", Path.home() / ".codex" / "skills" / "wafer-guide"))
+
+    if not targets_to_install:
+        typer.echo(f"Error: Unknown target '{target}'. Use: claude, codex, or all", err=True)
+        raise typer.Exit(1)
+
+    for tool_name, dest_path in targets_to_install:
+        # Check if already exists
+        if dest_path.exists():
+            if not force:
+                typer.echo(f"  {tool_name}: Already installed at {dest_path}")
+                typer.echo("             Use --force to overwrite")
+                continue
+            # Remove existing
+            if dest_path.is_symlink():
+                dest_path.unlink()
+            else:
+                import shutil
+
+                shutil.rmtree(dest_path)
+
+        # Create parent directory
+        dest_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Create symlink
+        dest_path.symlink_to(skill_source)
+        typer.echo(f"  {tool_name}: Installed at {dest_path}")
+
+    typer.echo("")
+    typer.echo("Restart your AI assistant to load the new skill.")
+
+
+@skill_app.command("uninstall")
+def skill_uninstall(
+    target: str = typer.Option(
+        "all",
+        "--target",
+        "-t",
+        help="Target tool: claude, codex, or all",
+    ),
+) -> None:
+    """Uninstall the wafer-guide skill.
+
+    Examples:
+        wafer skill uninstall              # Uninstall from both
+        wafer skill uninstall -t claude    # Uninstall from Claude Code only
+    """
+    targets_to_uninstall: list[tuple[str, Path]] = []
+
+    if target in ("all", "claude"):
+        targets_to_uninstall.append((
+            "Claude Code",
+            Path.home() / ".claude" / "skills" / "wafer-guide",
+        ))
+    if target in ("all", "codex"):
+        targets_to_uninstall.append((
+            "Codex CLI",
+            Path.home() / ".codex" / "skills" / "wafer-guide",
+        ))
+
+    if not targets_to_uninstall:
+        typer.echo(f"Error: Unknown target '{target}'. Use: claude, codex, or all", err=True)
+        raise typer.Exit(1)
+
+    for tool_name, dest_path in targets_to_uninstall:
+        if not dest_path.exists():
+            typer.echo(f"  {tool_name}: Not installed")
+            continue
+
+        if dest_path.is_symlink():
+            dest_path.unlink()
+        else:
+            import shutil
+
+            shutil.rmtree(dest_path)
+        typer.echo(f"  {tool_name}: Uninstalled from {dest_path}")
+
+
+@skill_app.command("status")
+def skill_status() -> None:
+    """Show installation status of the wafer-guide skill.
+
+    Examples:
+        wafer skill status
+    """
+    skill_source = Path(__file__).parent / "skills" / "wafer-guide"
+
+    typer.echo("Wafer Skill Status")
+    typer.echo("=" * 40)
+    typer.echo(f"Bundled skill: {skill_source}")
+    typer.echo(f"  Exists: {skill_source.exists()}")
+    typer.echo("")
+
+    installations = [
+        ("Claude Code", Path.home() / ".claude" / "skills" / "wafer-guide"),
+        ("Codex CLI", Path.home() / ".codex" / "skills" / "wafer-guide"),
+    ]
+
+    for tool_name, path in installations:
+        if path.exists():
+            if path.is_symlink():
+                target = path.resolve()
+                typer.echo(f"{tool_name}: Installed (symlink -> {target})")
+            else:
+                typer.echo(f"{tool_name}: Installed (copy at {path})")
+        else:
+            typer.echo(f"{tool_name}: Not installed")
+
 
 @app.command(hidden=True)
 def run(
@@ -1768,17 +2039,31 @@ def login(
     token: str | None = typer.Option(
         None, "--token", "-t", help="Access token (skip browser OAuth)"
     ),
+    port: int | None = typer.Option(
+        None, "--port", "-p", help="Port for OAuth callback server (default: 8765 for SSH, random for local)"
+    ),
 ) -> None:
     """Authenticate CLI with wafer-api via GitHub OAuth.
 
     Opens browser for GitHub authentication. Use --token to skip browser.
     Uses the API environment from config (see 'wafer config show').
 
+    SSH Users:
+    - Automatically uses port 8765 (just set up port forwarding once)
+    - On local machine: ssh -L 8765:localhost:8765 user@host
+    - On remote machine: wafer login
+    - Browser opens locally, redirect works through tunnel
+
+    Manual token option:
+    - Visit auth.wafer.ai, authenticate, copy token from URL
+    - Run: wafer login --token <paste-token>
+
     Examples:
-        wafer login              # opens browser for GitHub OAuth
-        wafer login --token xyz  # use existing token
+        wafer login                    # auto-detects SSH, uses appropriate port
+        wafer login --port 9000        # override port
+        wafer login --token xyz        # manual token (no browser)
 
-        # To login to a different environment:
+        # Change environment:
         wafer config set api.environment staging
         wafer login
     """
@@ -1794,11 +2079,21 @@ def login(
     typer.echo(f"Auth: {get_supabase_url()}")
     typer.echo("")
 
+    # Auto-detect SSH and use fixed port
+    if port is None:
+        is_ssh = bool(os.environ.get("SSH_CONNECTION") or os.environ.get("SSH_CLIENT"))
+        if is_ssh:
+            port = 8765
+            typer.echo("🔒 SSH session detected - using port 8765 for OAuth callback")
+            typer.echo("   Make sure you have port forwarding set up:")
+            typer.echo("   ssh -L 8765:localhost:8765 user@host")
+            typer.echo("")
+
     # Browser OAuth if no token provided
     refresh_token = None
     if token is None:
         try:
-            token, refresh_token = browser_login()
+            token, refresh_token = browser_login(port=port)
         except TimeoutError as e:
             typer.echo(f"Error: {e}", err=True)
             raise typer.Exit(1) from None
@@ -1832,6 +2127,11 @@ def login(
     # Save credentials (with refresh token if available)
     save_credentials(token, refresh_token, user_info.email)
 
+    # Track login event with analytics
+    from . import analytics
+
+    analytics.track_login(user_info.user_id, user_info.email)
+
     if user_info.email:
         typer.echo(f"Logged in as {user_info.email}")
     else:
@@ -1844,6 +2144,13 @@ def logout() -> None:
     """Remove stored credentials."""
     from .auth import clear_credentials
 
+    from . import analytics
+
+    # Track logout event first (while credentials still exist for user identification)
+    # Note: track_logout() handles the case where user is not logged in
+    analytics.track_logout()
+
+    # Clear credentials and report result
     if clear_credentials():
         typer.echo("Logged out. Credentials removed.")
     else:
@@ -1920,7 +2227,13 @@ def guide() -> None:
 # =============================================================================
 
 # Demo subcommand group
-demo_app = typer.Typer(help="Demo commands and sample data")
+demo_app = typer.Typer(
+    help="""Interactive demos for Wafer workflows.
+
+  wafer demo docs   Query GPU documentation (downloads ~5MB)
+  wafer demo trace  Analyze a sample performance trace
+  wafer demo eval   Run kernel evaluation on cloud GPU (requires login)"""
+)
 app.add_typer(demo_app, name="demo")
 
 DEMO_TRACES_URL = "https://github.com/wafer-ai/wafer/raw/main/apps/wafer-cli/wafer/demo_data"
@@ -2009,73 +2322,309 @@ def demo_traces() -> None:
     )
 
 
-@demo_app.command("examples")
-def demo_examples() -> None:
-    """Show example commands for common workflows.
+@demo_app.command("docs")
+def demo_docs(
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+) -> None:
+    """Demo: Ask GPU documentation questions.
+
+    Downloads CUDA corpus (~5MB) and asks a sample question using AI.
 
-    Prints copy-paste ready examples for:
-    - Analyzing traces
-    - Asking documentation questions
-    - Evaluating kernels
+    Example:
+        wafer demo docs
+        wafer demo docs -y  # skip confirmation
     """
-    typer.echo("""# Wafer CLI Examples
+    import subprocess
 
-## 1. Set Up GPU Access (one-time)
+    from .corpus import download_corpus, get_corpus_path
 
-# Option A: Your own GPU via SSH
-wafer config targets init ssh --name my-gpu --host user@hostname:22 --gpu-type H100
+    # Check if already downloaded
+    corpus_path = get_corpus_path("cuda")
+    needs_download = corpus_path is None
 
-# Option B: RunPod (on-demand cloud GPUs)
-export WAFER_RUNPOD_API_KEY=your_key  # from runpod.io/console/user/settings
-wafer config targets init runpod --gpu MI300X
+    if needs_download and not yes:
+        typer.echo("This demo will:")
+        typer.echo("  1. Download CUDA documentation corpus (~5MB)")
+        typer.echo("  2. Ask a sample question using AI")
+        typer.echo("")
+        if not typer.confirm("Continue?"):
+            raise typer.Exit(0)
 
-# Option C: DigitalOcean (AMD MI300X)
-export WAFER_AMD_DIGITALOCEAN_API_KEY=your_key
-wafer config targets init digitalocean
+    # Step 1: Download corpus if needed
+    if needs_download:
+        typer.echo("\n[1/2] Downloading CUDA corpus...")
+        download_corpus("cuda")
+    else:
+        typer.echo("\n[1/2] CUDA corpus already downloaded")
 
-# Verify your target
-wafer config targets list
+    # Step 2: Ask a question
+    typer.echo("\n[2/2] Asking: 'What is warp divergence?'\n")
+    typer.echo("-" * 60)
+    result = subprocess.run(
+        [
+            "wafer",
+            "wevin",
+            "-s",
+            "-t",
+            "ask-docs",
+            "--corpus",
+            "cuda",
+            "What is warp divergence? Answer in 2-3 sentences.",
+        ],
+        check=False,
+    )
+    typer.echo("-" * 60)
 
-## 2. Evaluate a Kernel
+    if result.returncode == 0:
+        typer.echo("\n✓ Demo complete! Try your own questions:")
+        typer.echo('  wafer agent -t ask-docs --corpus cuda "your question here"')
+    else:
+        typer.echo("\n✗ Demo failed. Check your configuration.")
+        raise typer.Exit(1)
 
-# Generate template files
-wafer evaluate make-template ./my-kernel
 
-# Run evaluation
-wafer evaluate \\
-  --impl ./my-kernel/kernel.py \\
-  --reference ./my-kernel/reference.py \\
-  --test-cases ./my-kernel/test_cases.json \\
-  --target my-gpu  # or runpod-mi300x, do-mi300x
+@demo_app.command("trace")
+def demo_trace(
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+) -> None:
+    """Demo: Analyze a performance trace.
 
-## 3. Ask GPU Programming Questions (no GPU needed)
+    Creates a sample PyTorch trace and runs SQL queries on it.
 
-# Download CUDA documentation (one-time)
-wafer corpus download cuda
+    Example:
+        wafer demo trace
+        wafer demo trace -y  # skip confirmation
+    """
+    import subprocess
 
-# Ask a question
-wafer wevin -t ask-docs --corpus cuda -s "What is warp divergence?"
+    if not yes:
+        typer.echo("This demo will:")
+        typer.echo("  1. Create a sample PyTorch-style trace")
+        typer.echo("  2. Run SQL queries to find slowest kernels")
+        typer.echo("")
+        if not typer.confirm("Continue?"):
+            raise typer.Exit(0)
 
-## 4. Analyze a PyTorch Trace (no GPU needed)
+    # Step 1: Setup demo data
+    typer.echo("\n[1/2] Creating sample trace...")
+    DEMO_DIR.mkdir(parents=True, exist_ok=True)
+    sample_trace = DEMO_DIR / "sample_trace.json"
+    sample_trace.write_text("""{
+  "traceEvents": [
+    {"name": "matmul_kernel", "cat": "kernel", "ph": "X", "ts": 0, "dur": 1500000, "pid": 1, "tid": 1},
+    {"name": "relu_kernel", "cat": "kernel", "ph": "X", "ts": 1600000, "dur": 50000, "pid": 1, "tid": 1},
+    {"name": "softmax_kernel", "cat": "kernel", "ph": "X", "ts": 1700000, "dur": 200000, "pid": 1, "tid": 1},
+    {"name": "attention_kernel", "cat": "kernel", "ph": "X", "ts": 2000000, "dur": 3000000, "pid": 1, "tid": 1},
+    {"name": "layernorm_kernel", "cat": "kernel", "ph": "X", "ts": 5100000, "dur": 100000, "pid": 1, "tid": 1}
+  ]
+}""")
+    typer.echo(f"  Created: {sample_trace}")
+
+    # Step 2: Query the trace
+    typer.echo("\n[2/2] Finding slowest kernels...\n")
+    typer.echo("-" * 60)
+    result = subprocess.run(
+        [
+            "wafer",
+            "nvidia",
+            "perfetto",
+            "query",
+            str(sample_trace),
+            "SELECT name, dur/1e6 as duration_ms FROM slice ORDER BY dur DESC",
+        ],
+        check=False,
+    )
+    typer.echo("-" * 60)
+
+    if result.returncode == 0:
+        typer.echo("\n✓ Demo complete! Try your own traces:")
+        typer.echo('  wafer nvidia perfetto query <your_trace.json> "SELECT name, dur FROM slice"')
+        typer.echo("")
+        typer.echo("  Or use AI-assisted analysis:")
+        typer.echo('  wafer agent -t trace-analyze --args trace=<your_trace.json> "What\'s slow?"')
+    else:
+        typer.echo("\n✗ Demo failed.")
+        raise typer.Exit(1)
+
+
+@demo_app.command("eval")
+def demo_eval(
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+) -> None:
+    """Demo: Evaluate a kernel on a cloud GPU.
+
+    Creates a workspace, runs a sample Triton kernel evaluation, and cleans up.
+    Requires authentication (wafer login).
 
-# Setup demo data
-wafer demo setup
+    Example:
+        wafer demo eval
+        wafer demo eval -y  # skip confirmation
+    """
+    import subprocess
+    import tempfile
+    import time
+
+    from .auth import load_credentials
+
+    # Check auth first
+    creds = load_credentials()
+    if not creds:
+        typer.echo("Error: Not authenticated. Run: wafer login")
+        raise typer.Exit(1)
+
+    if not yes:
+        typer.echo("This demo will:")
+        typer.echo("  1. Create a cloud GPU workspace (B200)")
+        typer.echo("  2. Generate and upload a sample Triton kernel")
+        typer.echo("  3. Run correctness + performance evaluation")
+        typer.echo("  4. Delete the workspace")
+        typer.echo("")
+        typer.echo("  Note: Workspace usage is billed. Demo takes ~2-3 minutes.")
+        typer.echo("")
+        if not typer.confirm("Continue?"):
+            raise typer.Exit(0)
+
+    workspace_name = f"wafer-demo-{int(time.time()) % 100000}"
+
+    try:
+        # Step 1: Create workspace
+        typer.echo(f"\n[1/4] Creating workspace '{workspace_name}'...")
+        result = subprocess.run(
+            ["wafer", "workspaces", "create", workspace_name, "--gpu", "B200", "--json"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        import json
+
+        ws_info = json.loads(result.stdout)
+        workspace_id = ws_info.get("id", workspace_name)
+        typer.echo(f"  Created: {workspace_id}")
+
+        # Step 2: Generate kernel template
+        typer.echo("\n[2/4] Generating sample kernel...")
+        with tempfile.TemporaryDirectory() as tmpdir:
+            kernel_dir = Path(tmpdir) / "demo-kernel"
+            subprocess.run(
+                ["wafer", "evaluate", "make-template", str(kernel_dir)],
+                capture_output=True,
+                check=True,
+            )
+            typer.echo("  Generated Triton vector-add kernel")
 
-# Find slowest kernels
-wafer nvidia perfetto query ~/.cache/wafer/demo/sample_trace.json \\
-  "SELECT name, dur/1e6 as ms FROM slice WHERE cat='kernel' ORDER BY dur DESC"
+            # Step 3: Run evaluation
+            typer.echo("\n[3/4] Running evaluation on cloud GPU...\n")
+            typer.echo("-" * 60)
 
----
-For more details, run: wafer guide
+            # Write a simple test script to avoid escaping hell
+            test_script = kernel_dir / "run_test.py"
+            test_script.write_text("""
+import torch
+import kernel
+import reference
+
+print(f"GPU: {torch.cuda.get_device_name(0)}")
+
+# Test correctness
+inputs = reference.generate_input(n=1048576, seed=42)
+out = kernel.custom_kernel(inputs)
+ref = reference.ref_kernel(inputs)
+correct = torch.allclose(out, ref)
+print(f"Correctness: {correct}")
+
+# Benchmark
+import time
+for _ in range(10):
+    kernel.custom_kernel(inputs)
+torch.cuda.synchronize()
+
+t0 = time.perf_counter()
+for _ in range(100):
+    kernel.custom_kernel(inputs)
+torch.cuda.synchronize()
+t1 = time.perf_counter()
+
+print(f"Performance: {(t1-t0)/100*1e6:.1f} us/iter")
 """)
 
+            eval_result = subprocess.run(
+                [
+                    "wafer",
+                    "workspaces",
+                    "exec",
+                    "--sync",
+                    str(kernel_dir),
+                    workspace_name,
+                    "--",
+                    "bash",
+                    "-c",
+                    "cd /workspace && uv pip install -q --system triton && python run_test.py",
+                ],
+                check=False,
+            )
+            typer.echo("-" * 60)
+
+        # Step 4: Cleanup
+        typer.echo(f"\n[4/4] Deleting workspace '{workspace_name}'...")
+        subprocess.run(
+            ["wafer", "workspaces", "delete", workspace_id],
+            capture_output=True,
+            check=False,
+        )
+        typer.echo("  Deleted")
+
+        if eval_result.returncode == 0:
+            typer.echo("\n✓ Demo complete! To evaluate your own kernels:")
+            typer.echo("")
+            typer.echo("  # Using workspaces (no setup required):")
+            typer.echo("  wafer workspaces create dev --gpu B200")
+            typer.echo("  wafer workspaces exec --sync ./my-kernel dev -- python my_test.py")
+            typer.echo("")
+            typer.echo("  # Or using wafer evaluate with a configured target:")
+            typer.echo("  wafer evaluate make-template ./my-kernel")
+            typer.echo("  wafer evaluate --impl ./my-kernel/kernel.py \\")
+            typer.echo("      --reference ./my-kernel/reference.py \\")
+            typer.echo("      --test-cases ./my-kernel/test_cases.json \\")
+            typer.echo("      --target <your-target>")
+        else:
+            typer.echo("\n✗ Evaluation failed, but workspace was cleaned up.")
+            raise typer.Exit(1)
+
+    except subprocess.CalledProcessError as e:
+        error_msg = e.stderr.strip() if e.stderr else str(e)
+        typer.echo(f"\n✗ Error: {error_msg}")
+        # Try to cleanup on failure
+        typer.echo(f"Attempting to cleanup workspace '{workspace_name}'...")
+        subprocess.run(
+            ["wafer", "workspaces", "delete", workspace_name],
+            capture_output=True,
+            check=False,
+        )
+        raise typer.Exit(1) from None
+    except KeyboardInterrupt:
+        typer.echo(f"\n\nInterrupted. Cleaning up workspace '{workspace_name}'...")
+        subprocess.run(
+            ["wafer", "workspaces", "delete", workspace_name],
+            capture_output=True,
+            check=False,
+        )
+        raise typer.Exit(1) from None
+
 
 # =============================================================================
 # Targets subcommands
 # =============================================================================
 
 # Init subcommand group for interactive target setup
-init_app = typer.Typer(help="Initialize a new target interactively")
+init_app = typer.Typer(
+    help="""Initialize a new GPU target.
+
+Choose based on your GPU access:
+
+  ssh          Your own hardware via SSH
+  runpod       RunPod cloud GPUs (needs WAFER_RUNPOD_API_KEY)
+  digitalocean DigitalOcean AMD MI300X (needs WAFER_AMD_DIGITALOCEAN_API_KEY)"""
+)
 targets_app.add_typer(init_app, name="init")
 
 
@@ -2533,6 +3082,118 @@ def targets_pods() -> None:
         typer.echo()
 
 
+# =============================================================================
+# Billing commands
+# =============================================================================
+
+
+@billing_app.callback(invoke_without_command=True)
+def billing_usage(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+) -> None:
+    """Show current billing usage and subscription info.
+
+    Example:
+        wafer billing
+        wafer billing --json
+    """
+    # Only show usage if no subcommand was invoked
+    if ctx.invoked_subcommand is not None:
+        return
+
+    from .billing import get_usage
+
+    try:
+        result = get_usage(json_output=json_output)
+        typer.echo(result)
+    except RuntimeError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1) from None
+
+
+@billing_app.command("topup")
+def billing_topup(
+    amount: int = typer.Argument(25, help="Amount in dollars ($10-$500)"),
+    no_browser: bool = typer.Option(False, "--no-browser", help="Print URL instead of opening browser"),
+) -> None:
+    """Add credits to your account.
+
+    Opens a Stripe checkout page to add credits. Default amount is $25.
+
+    Example:
+        wafer billing topup        # Add $25
+        wafer billing topup 100    # Add $100
+        wafer billing topup --no-browser  # Print URL instead
+    """
+    import webbrowser
+
+    from .billing import create_topup, validate_topup_amount
+
+    # Convert dollars to cents
+    amount_cents = amount * 100
+
+    # Validate amount client-side before API call
+    try:
+        validate_topup_amount(amount_cents)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1) from None
+
+    try:
+        result = create_topup(amount_cents)
+        checkout_url = result.get("checkout_url")
+
+        if not checkout_url:
+            typer.echo("Error: No checkout URL received from API", err=True)
+            raise typer.Exit(1) from None
+
+        if no_browser:
+            typer.echo(f"Complete your purchase at:\n{checkout_url}")
+        else:
+            typer.echo(f"Opening checkout for ${amount}...")
+            webbrowser.open(checkout_url)
+            typer.echo("Browser opened. Complete your purchase there.")
+    except RuntimeError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1) from None
+
+
+@billing_app.command("portal")
+def billing_portal(
+    no_browser: bool = typer.Option(False, "--no-browser", help="Print URL instead of opening browser"),
+) -> None:
+    """Open Stripe billing portal.
+
+    Manage your subscription, update payment method, or view invoices.
+
+    Example:
+        wafer billing portal
+        wafer billing portal --no-browser
+    """
+    import webbrowser
+
+    from .billing import get_portal_url
+
+    try:
+        result = get_portal_url()
+        portal_url = result.get("portal_url")
+
+        if not portal_url:
+            typer.echo("Error: No portal URL received from API", err=True)
+            raise typer.Exit(1) from None
+
+        if no_browser:
+            typer.echo(f"Billing portal:\n{portal_url}")
+        else:
+            typer.echo("Opening billing portal...")
+            webbrowser.open(portal_url)
+            typer.echo("Browser opened.")
+    except RuntimeError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1) from None
+
+
 # =============================================================================
 # Workspaces commands
 # =============================================================================
@@ -3767,6 +4428,29 @@ autotuner_app = typer.Typer(help="Hyperparameter sweep for performance engineeri
 app.add_typer(autotuner_app, name="autotuner", hidden=True)
 
 
+def _setup_wafer_core_env() -> None:
+    """Set environment variables for wafer-core to use.
+
+    Call this before using any wafer-core functions that need API access.
+
+    Respects explicit environment variable overrides:
+    - WAFER_API_URL: If already set, uses that instead of config
+    - WAFER_AUTH_TOKEN: If already set, uses that instead of cached token
+    """
+    from .global_config import get_api_url
+    from .auth import get_valid_token
+
+    # Set API URL (get_api_url already respects WAFER_API_URL env var)
+    os.environ["WAFER_API_URL"] = get_api_url()
+
+    # Only set auth token if not explicitly provided in environment
+    # This allows CI/service accounts to override with their own tokens
+    if "WAFER_AUTH_TOKEN" not in os.environ:
+        token = get_valid_token()
+        if token:
+            os.environ["WAFER_AUTH_TOKEN"] = token
+
+
 @autotuner_app.command("list")
 def autotuner_list(
     show_all: bool = typer.Option(
@@ -3782,6 +4466,7 @@ def autotuner_list(
         wafer autotuner list
         wafer autotuner list --all
     """
+    _setup_wafer_core_env()
     from .autotuner import list_command
 
     try:
@@ -3822,6 +4507,7 @@ def autotuner_delete(
         wafer autotuner delete --all --status pending
         wafer autotuner delete --all --status failed --yes
     """
+    _setup_wafer_core_env()
     from .autotuner import delete_all_command, delete_command
 
     # Validate arguments
@@ -3888,6 +4574,7 @@ def autotuner_run(
         wafer autotuner run --resume <sweep-id>
         wafer autotuner run --resume <sweep-id> --parallel 8
     """
+    _setup_wafer_core_env()
     from .autotuner import run_sweep_command
 
     # Validate arguments
@@ -4052,8 +4739,23 @@ def capture_command(  # noqa: PLR0915
         wafer capture grid-search "python train.py --lr {LR} --bs {BS}" --sweep "LR=0.001,0.01,0.1" --sweep "BS=16,32"
     """
     import itertools
+    import os
     import tomllib
 
+    from .global_config import get_api_url
+    from .auth import get_valid_token
+
+    # Set environment variables for wafer-core BEFORE importing it
+    # wafer-core backend.py reads WAFER_API_URL and WAFER_AUTH_TOKEN from env
+    os.environ["WAFER_API_URL"] = get_api_url()
+
+    # Only set auth token if not explicitly provided in environment
+    # This allows CI/service accounts to override with their own tokens
+    if "WAFER_AUTH_TOKEN" not in os.environ:
+        token = get_valid_token()
+        if token:
+            os.environ["WAFER_AUTH_TOKEN"] = token
+
     import trio
     from wafer_core.tools.capture_tool import (  # pragma: no cover
         CaptureConfig,
@@ -4243,6 +4945,20 @@ def capture_list_command(
         # Pagination
         wafer capture-list --limit 20 --offset 20
     """
+    import os
+
+    from .global_config import get_api_url
+    from .auth import get_valid_token
+
+    # Set environment variables for wafer-core BEFORE importing it
+    os.environ["WAFER_API_URL"] = get_api_url()
+
+    # Only set auth token if not explicitly provided in environment
+    # This allows CI/service accounts to override with their own tokens
+    if "WAFER_AUTH_TOKEN" not in os.environ:
+        token = get_valid_token()
+        if token:
+            os.environ["WAFER_AUTH_TOKEN"] = token
 
     import trio
     from wafer_core.utils.backend import list_captures  # pragma: no cover