msapling-cli 0.1.2__py3-none-any.whl

msapling_cli/main.py

@@ -0,0 +1,1038 @@
+"""MSapling CLI - Multi-chat AI development environment in your terminal.
+
+Usage:
+    msapling login                          # Authenticate
+    msapling chat "explain this code"       # Quick chat
+    msapling chat -i                        # Interactive chat session
+    msapling edit "add type hints" main.py  # LLM-driven file editing
+    msapling diff old.py new.py             # Generate unified diff
+    msapling ls                             # List MDrive files
+    msapling cat src/main.py                # View file content
+    msapling models                         # List available models
+    msapling projects                       # List projects
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+import uuid
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.live import Live
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.status import Status
+from rich.syntax import Syntax
+from rich.table import Table
+from rich.prompt import Prompt
+
+from . import __version__
+from .config import get_settings, save_settings, get_token, save_token, clear_token, Settings
+from .api import MSaplingClient, OfflineError
+from .tier import require_pro, require_auth, is_free_model
+
+# Cache user info for tier checks within a session
+_cached_user: dict = {}
+
+
+def _version_callback(value: bool):
+    if value:
+        Console().print(f"msapling-cli v{__version__}")
+        raise typer.Exit()
+
+
+def _default_callback(
+    ctx: typer.Context,
+    version: bool = typer.Option(False, "--version", "-V", callback=_version_callback, is_eager=True, help="Show version"),
+    prompt: Optional[str] = typer.Option(None, "-p", "--prompt", help="Non-interactive: run prompt and exit (headless mode)"),
+    headless_model: Optional[str] = typer.Option(None, "--model", "-m", help="Model for headless mode"),
+    output_format: str = typer.Option("text", "--output", "-o", help="Output format: text, json, stream-json"),
+    max_turns: int = typer.Option(1, "--max-turns", help="Max agent turns in headless mode"),
+):
+    """Launch interactive shell when no command is given. Use -p for headless mode."""
+    if ctx.invoked_subcommand is None:
+        if prompt:
+            # Headless mode: run single prompt, print result, exit
+            _run(_headless(prompt, headless_model, output_format, max_turns))
+        else:
+            from .shell import run_shell
+            asyncio.run(run_shell())
+
+
+app = typer.Typer(
+    name="msapling",
+    help="MSapling CLI - Multi-chat AI development in your terminal",
+    invoke_without_command=True,
+    callback=_default_callback,
+)
+console = Console()
+
+
+def _run(coro):
+    """Run async function in sync context."""
+    return asyncio.run(coro)
+
+
+async def _headless(prompt: str, model: Optional[str], output_format: str, max_turns: int):
+    """Non-interactive headless execution. Like `claude -p` or `codex exec`."""
+    import json as _json
+    settings = get_settings()
+    model_id = model or settings.default_model
+    token = get_token()
+    if not token:
+        console.print("[red]Not logged in. Run: msapling login[/red]", style="bold red")
+        raise SystemExit(1)
+
+    client = MSaplingClient()
+    try:
+        chat_id = str(uuid.uuid4())
+        if max_turns > 1:
+            # Agent mode: run tool loop
+            from .agent import run_agent_loop
+            from .local import detect_project_root
+            project_root, _ = detect_project_root(".")
+            messages: list = []
+            result = await run_agent_loop(
+                client=client, prompt=prompt, model=model_id,
+                project_root=project_root, messages=messages,
+                on_text=None,
+            )
+            if output_format == "json":
+                print(_json.dumps({"response": result, "model": model_id}))
+            else:
+                print(result)
+        else:
+            # Single-shot streaming
+            parts = []
+            usage_data = {}
+            async for chunk in client.stream_chat(
+                chat_id=chat_id, prompt=prompt, model=model_id,
+            ):
+                content = chunk.get("content", "")
+                if content:
+                    parts.append(content)
+                    if output_format == "stream-json":
+                        print(_json.dumps({"type": "content", "text": content}))
+                if chunk.get("type") == "usage":
+                    usage_data = chunk
+            response = "".join(parts)
+            if output_format == "json":
+                print(_json.dumps({
+                    "response": response, "model": model_id,
+                    "tokens": usage_data.get("usage", {}).get("total_tokens", 0),
+                    "cost": usage_data.get("cost", 0),
+                }))
+            elif output_format == "stream-json":
+                print(_json.dumps({"type": "done", "tokens": usage_data.get("usage", {}).get("total_tokens", 0)}))
+            else:
+                print(response)
+    except Exception as e:
+        if output_format == "json":
+            print(_json.dumps({"error": str(e)}))
+        else:
+            console.print(f"[red]{e}[/red]")
+        raise SystemExit(1)
+    finally:
+        await client.close()
+
+
+def _get_user_or_exit() -> dict:
+    """Fetch user info (cached). Exits if not authenticated. Handles offline."""
+    require_auth(get_token())
+    if _cached_user:
+        return _cached_user
+
+    async def _fetch():
+        client = MSaplingClient()
+        try:
+            user = await client.me()
+            _cached_user.update(user)
+            return user
+        except OfflineError:
+            console.print("[red]Cannot reach MSapling API. Check your connection or use offline commands (scan, context, git).[/red]")
+            raise SystemExit(1)
+        except Exception as e:
+            console.print(f"[red]Auth failed: {e}[/red]")
+            raise SystemExit(1)
+        finally:
+            await client.close()
+
+    return _run(_fetch())
+
+
+# ─── Auth ─────────────────────────────────────────────────────────────
+
+@app.command()
+def register(
+    email: str = typer.Option(..., prompt=True),
+    password: str = typer.Option(..., prompt=True, hide_input=True, confirmation_prompt=True),
+    api_url: Optional[str] = typer.Option(None, help="API URL override"),
+):
+    """Create a new MSapling account from the terminal."""
+    async def _register():
+        client = MSaplingClient(api_url=api_url)
+        try:
+            http = await client._get_client()
+            resp = await http.post("/auth/register", json={
+                "email": email,
+                "password": password,
+            })
+            if resp.status_code in (200, 201):
+                console.print(f"[green]Account created for {email}[/green]")
+                console.print("[dim]Logging in...[/dim]")
+                # Auto-login after register
+                await client.login(email, password)
+                if client.token:
+                    save_token(client.token)
+                    if api_url:
+                        settings = get_settings()
+                        settings.api_url = api_url
+                        save_settings(settings)
+                    user = await client.me()
+                    console.print(f"[green]Logged in as {user.get('email', email)}[/green]")
+                    console.print(f"  Tier: {user.get('tier', 'free')}")
+                    console.print(f"  Fuel: ${user.get('fuel_credits', 0):.4f}")
+            elif resp.status_code == 400:
+                detail = resp.json().get("detail", "Registration failed")
+                console.print(f"[red]{detail}[/red]")
+            elif resp.status_code == 409:
+                console.print(f"[yellow]Account already exists for {email}. Use: msapling login[/yellow]")
+            else:
+                console.print(f"[red]Registration failed (HTTP {resp.status_code})[/red]")
+        except Exception as e:
+            console.print(f"[red]Registration failed: {e}[/red]")
+        finally:
+            await client.close()
+
+    _run(_register())
+
+
+@app.command()
+def login(
+    email: str = typer.Option(..., prompt=True),
+    password: str = typer.Option(..., prompt=True, hide_input=True),
+    api_url: Optional[str] = typer.Option(None, help="API URL override"),
+):
+    """Authenticate with MSapling backend."""
+    async def _login():
+        client = MSaplingClient(api_url=api_url)
+        try:
+            result = await client.login(email, password)
+            if client.token:
+                save_token(client.token)
+                if api_url:
+                    settings = get_settings()
+                    settings.api_url = api_url
+                    save_settings(settings)
+                user = await client.me()
+                console.print(f"[green]Logged in as {user.get('email', email)}[/green]")
+                console.print(f"  Tier: {user.get('tier', 'free')}")
+                console.print(f"  Fuel: ${user.get('fuel_credits', 0):.4f}")
+            else:
+                console.print("[red]Login failed - no token received[/red]")
+        except Exception as e:
+            console.print(f"[red]Login failed: {e}[/red]")
+        finally:
+            await client.close()
+
+    _run(_login())
+
+
+@app.command()
+def logout():
+    """Clear saved authentication."""
+    clear_token()
+    console.print("[yellow]Logged out[/yellow]")
+
+
+@app.command()
+def whoami():
+    """Show current user info."""
+    async def _whoami():
+        client = MSaplingClient()
+        try:
+            user = await client.me()
+            table = Table(title="Account")
+            table.add_column("Field", style="cyan")
+            table.add_column("Value")
+            table.add_row("Email", str(user.get("email", "?")))
+            table.add_row("Tier", str(user.get("tier", "free")))
+            table.add_row("Fuel Credits", f"${user.get('fuel_credits', 0):.4f}")
+            table.add_row("Pro", str(user.get("is_pro", False)))
+            console.print(table)
+        except Exception as e:
+            console.print(f"[red]Not authenticated: {e}[/red]")
+        finally:
+            await client.close()
+
+    _run(_whoami())
+
+
+# ─── Chat ─────────────────────────────────────────────────────────────
+
+@app.command()
+def chat(
+    prompt: Optional[str] = typer.Argument(None, help="Message to send"),
+    model: Optional[str] = typer.Option(None, "-m", help="Model ID"),
+    project: Optional[str] = typer.Option(None, "-p", help="Project name"),
+    interactive: bool = typer.Option(False, "-i", help="Interactive session"),
+    agent: bool = typer.Option(False, "-a", help="Enable agent mode"),
+):
+    """Chat with an LLM. Use -i for interactive session.
+
+    Free tier: Flash, Haiku, Mini, Llama, Mistral models only.
+    Pro tier: All models + unlimited messages.
+    """
+    from .completer import resolve_model
+    settings = get_settings()
+    raw_model = model or settings.default_model
+    model_id, was_fuzzy = resolve_model(raw_model)
+    if was_fuzzy and model:
+        console.print(f"[dim]Model: {model} -> {model_id}[/dim]")
+    user = _get_user_or_exit()
+    require_pro(user, "chat", model_id)
+    chat_id = str(uuid.uuid4())
+
+    async def _chat_once(msg: str):
+        client = MSaplingClient()
+        try:
+            parts = []
+            with Live(console=console, refresh_per_second=15) as live:
+                async for chunk in client.stream_chat(
+                    chat_id=chat_id,
+                    prompt=msg,
+                    model=model_id,
+                    project_name=project,
+                    agent_mode=agent,
+                ):
+                    content = chunk.get("content", "")
+                    if content:
+                        parts.append(content)
+                        text = "".join(parts)
+                        live.update(Markdown(text))
+                    if chunk.get("type") == "usage":
+                        usage = chunk.get("usage", {})
+                        tokens = usage.get("total_tokens", 0)
+                        cost = chunk.get("cost", 0)
+                        console.print(f"\n[dim]({tokens} tokens, ${cost:.4f})[/dim]")
+            if not parts:
+                console.print("[yellow]No response received[/yellow]")
+        except Exception as e:
+            console.print(f"[red]Error: {e}[/red]")
+        finally:
+            await client.close()
+
+    if interactive:
+        console.print(f"[cyan]MSapling Chat[/cyan] | model: {model_id} | type 'exit' to quit")
+        console.print("─" * 60)
+        while True:
+            try:
+                msg = Prompt.ask("[bold green]You[/bold green]")
+                if msg.lower() in ("exit", "quit", "q"):
+                    break
+                if not msg.strip():
+                    continue
+                _run(_chat_once(msg))
+                console.print()
+            except (KeyboardInterrupt, EOFError):
+                break
+        console.print("[yellow]Session ended[/yellow]")
+    elif prompt:
+        _run(_chat_once(prompt))
+    else:
+        console.print("[yellow]Provide a prompt or use -i for interactive mode[/yellow]")
+
+
+# ─── Multi-Chat & Swarm ───────────────────────────────────────────────
+
+@app.command()
+def multi(
+    prompt: str = typer.Argument(..., help="Prompt to send to all models"),
+    models: str = typer.Option(
+        "google/gemini-flash-1.5,anthropic/claude-3-haiku,openai/gpt-4o-mini",
+        "-m", help="Comma-separated model IDs",
+    ),
+):
+    """Send the same prompt to multiple models in parallel. Compare responses side-by-side.
+
+    Requires Pro subscription.
+    """
+    user = _get_user_or_exit()
+    require_pro(user, "multi")
+    model_list = [m.strip() for m in models.split(",") if m.strip()]
+    async def _multi():
+        client = MSaplingClient()
+        try:
+            with Status(f"Querying {len(model_list)} models in parallel...", console=console):
+                results = await client.multi_chat(prompt, model_list)
+            for r in results:
+                status_color = "green" if r["status"] == "ok" else "red"
+                console.print(Panel(
+                    Markdown(r["response"][:3000]) if r["response"] else f"[red]{r.get('error', 'No response')}[/red]",
+                    title=f"[{status_color}]{r['model']}[/{status_color}]",
+                    border_style=status_color,
+                ))
+        except Exception as e:
+            console.print(f"[red]Error: {e}[/red]")
+        finally:
+            await client.close()
+
+    _run(_multi())
+
+
+@app.command()
+def swarm(
+    prompt: str = typer.Argument(..., help="Task for the swarm"),
+    models: Optional[str] = typer.Option(None, "-m", help="Comma-separated models (default: gemini,claude,gpt)"),
+    judge: Optional[str] = typer.Option(None, "-j", help="Judge model for synthesis"),
+):
+    """Run a multi-model swarm: N models answer in parallel, then a judge synthesizes.
+
+    Requires Pro subscription.
+
+    Example:
+        msapling swarm "explain async/await" -m "gpt-4o,claude-3.5-sonnet,gemini-pro"
+    """
+    user = _get_user_or_exit()
+    require_pro(user, "swarm")
+    model_list = [m.strip() for m in models.split(",") if m.strip()] if models else None
+
+    async def _swarm():
+        client = MSaplingClient()
+        try:
+            with Status("Running swarm (parallel models + judge synthesis)...", console=console):
+                result = await client.swarm(prompt, models=model_list, synthesize_model=judge)
+
+            # Show individual agent responses
+            for r in result["agent_responses"]:
+                status = "[green]OK[/green]" if r["status"] == "ok" else "[red]FAIL[/red]"
+                console.print(f"\n[dim]── {r['model']} ({status}) ──[/dim]")
+                if r["response"]:
+                    console.print(Markdown(r["response"][:1500]))
+
+            # Show synthesis
+            console.print(Panel(
+                Markdown(result["synthesis"]),
+                title=f"[bold cyan]Synthesis by {result['judge_model']}[/bold cyan]",
+                border_style="cyan",
+            ))
+            console.print(f"[dim]Models used: {', '.join(result['models_used'])}[/dim]")
+        except Exception as e:
+            console.print(f"[red]Error: {e}[/red]")
+        finally:
+            await client.close()
+
+    _run(_swarm())
+
+
+# ─── Code Editing ─────────────────────────────────────────────────────
+
+@app.command()
+def edit(
+    instruction: str = typer.Argument(..., help="What to change"),
+    filepath: str = typer.Argument(..., help="File to edit"),
+    model: Optional[str] = typer.Option(None, "-m", help="Model ID"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show diff without applying"),
+):
+    """Edit a file using natural language instructions.
+
+    Requires Pro subscription.
+    """
+    user = _get_user_or_exit()
+    require_pro(user, "edit")
+    path = Path(filepath)
+    if not path.exists():
+        console.print(f"[red]File not found: {filepath}[/red]")
+        raise typer.Exit(1)
+
+    original = path.read_text(encoding="utf-8")
+    settings = get_settings()
+    model_id = model or settings.default_model
+    chat_id = str(uuid.uuid4())
+
+    prompt_text = (
+        f"Edit the following file according to this instruction: {instruction}\n\n"
+        f"File: {filepath}\n```\n{original}\n```\n\n"
+        f"Return ONLY a unified diff (no explanation). Start with --- and +++."
+    )
+
+    async def _edit():
+        client = MSaplingClient()
+        try:
+            parts = []
+            console.print(f"[cyan]Generating edit for {filepath}...[/cyan]")
+            async for chunk in client.stream_chat(
+                chat_id=chat_id,
+                prompt=prompt_text,
+                model=model_id,
+            ):
+                content = chunk.get("content", "")
+                if content:
+                    parts.append(content)
+
+            diff_text = "".join(parts)
+
+            # Show diff
+            console.print(Panel(
+                Syntax(diff_text, "diff", theme="monokai"),
+                title=f"Proposed changes to {filepath}",
+            ))
+
+            if dry_run:
+                console.print("[yellow]Dry run - no changes applied[/yellow]")
+                return
+
+            # Apply via MLineage
+            result = await client.apply_diff(original, diff_text)
+            if result.get("success") or result.get("applied_content"):
+                new_content = result.get("applied_content", "")
+                if new_content:
+                    path.write_text(new_content, encoding="utf-8")
+                    console.print(f"[green]Applied changes to {filepath}[/green]")
+                else:
+                    console.print("[yellow]Diff parsed but no content returned[/yellow]")
+            else:
+                console.print(f"[red]Failed to apply diff: {result.get('error', 'unknown')}[/red]")
+        except Exception as e:
+            console.print(f"[red]Error: {e}[/red]")
+        finally:
+            await client.close()
+
+    _run(_edit())
+
+
+# ─── Diff ─────────────────────────────────────────────────────────────
+
+@app.command()
+def diff(
+    old_file: str = typer.Argument(..., help="Original file"),
+    new_file: str = typer.Argument(..., help="Modified file"),
+):
+    """Generate a unified diff between two files."""
+    old_path, new_path = Path(old_file), Path(new_file)
+    if not old_path.exists():
+        console.print(f"[red]File not found: {old_file}[/red]")
+        raise typer.Exit(1)
+    if not new_path.exists():
+        console.print(f"[red]File not found: {new_file}[/red]")
+        raise typer.Exit(1)
+
+    async def _diff():
+        client = MSaplingClient()
+        try:
+            result = await client.generate_diff(
+                old_content=old_path.read_text(encoding="utf-8"),
+                new_content=new_path.read_text(encoding="utf-8"),
+                filename=old_file,
+            )
+            diff_text = result.get("diff", result.get("unified_diff", ""))
+            if diff_text:
+                console.print(Syntax(diff_text, "diff", theme="monokai"))
+            else:
+                console.print("[yellow]Files are identical[/yellow]")
+        except Exception as e:
+            console.print(f"[red]Error: {e}[/red]")
+        finally:
+            await client.close()
+
+    _run(_diff())
+
+
+# ─── File Operations ──────────────────────────────────────────────────
+
+@app.command(name="ls")
+def list_files(
+    project_id: str = typer.Argument("default", help="Project ID"),
+    path: str = typer.Option("/", help="Directory path"),
+):
+    """List files in an MDrive project."""
+    async def _ls():
+        client = MSaplingClient()
+        try:
+            files = await client.list_files(project_id, path)
+            if not files:
+                console.print("[yellow]No files found[/yellow]")
+                return
+            table = Table(title=f"Files in {project_id}:{path}")
+            table.add_column("Name", style="cyan")
+            table.add_column("Size", justify="right")
+            table.add_column("Modified")
+            for f in files:
+                name = f.get("name", f.get("file_path", "?"))
+                size = f.get("size", f.get("size_bytes", 0))
+                modified = f.get("modified", f.get("updated_at", ""))
+                size_str = f"{size / 1024:.1f} KB" if size > 1024 else f"{size} B"
+                table.add_row(name, size_str, str(modified)[:19])
+            console.print(table)
+        except Exception as e:
+            console.print(f"[red]Error: {e}[/red]")
+        finally:
+            await client.close()
+
+    _run(_ls())
+
+
+@app.command(name="cat")
+def read_file(
+    project_id: str = typer.Argument(..., help="Project ID"),
+    filepath: str = typer.Argument(..., help="File path"),
+):
+    """Read a file from MDrive."""
+    async def _cat():
+        client = MSaplingClient()
+        try:
+            content = await client.read_file(project_id, filepath)
+            ext = Path(filepath).suffix.lstrip(".")
+            lang_map = {"py": "python", "ts": "typescript", "js": "javascript", "tsx": "tsx", "md": "markdown"}
+            lang = lang_map.get(ext, ext)
+            console.print(Syntax(content, lang, theme="monokai", line_numbers=True))
+        except Exception as e:
+            console.print(f"[red]Error: {e}[/red]")
+        finally:
+            await client.close()
+
+    _run(_cat())
+
+
+# ─── Models & Projects ────────────────────────────────────────────────
+
+@app.command()
+def models():
+    """List available LLM models."""
+    async def _models():
+        client = MSaplingClient()
+        try:
+            model_list = await client.get_models()
+            table = Table(title="Available Models")
+            table.add_column("Model ID", style="cyan")
+            table.add_column("Provider")
+            table.add_column("Context", justify="right")
+            for m in model_list[:30]:
+                mid = m.get("id", m.get("model_id", "?"))
+                provider = mid.split("/")[0] if "/" in mid else "unknown"
+                ctx = m.get("context_length", m.get("context", "?"))
+                table.add_row(mid, provider, str(ctx))
+            console.print(table)
+            if len(model_list) > 30:
+                console.print(f"[dim]... and {len(model_list) - 30} more[/dim]")
+        except Exception as e:
+            console.print(f"[red]Error: {e}[/red]")
+        finally:
+            await client.close()
+
+    _run(_models())
+
+
+@app.command()
+def projects():
+    """List your projects."""
+    async def _projects():
+        client = MSaplingClient()
+        try:
+            proj_list = await client.list_projects()
+            table = Table(title="Projects")
+            table.add_column("Name", style="cyan")
+            table.add_column("Tokens Used", justify="right")
+            table.add_column("Cost", justify="right")
+            for p in proj_list:
+                name = p.get("name", "?")
+                tokens = p.get("tokens_used", 0)
+                cost = p.get("cost_used", 0)
+                table.add_row(name, f"{tokens:,}", f"${float(cost):.4f}")
+            console.print(table)
+        except Exception as e:
+            console.print(f"[red]Error: {e}[/red]")
+        finally:
+            await client.close()
+
+    _run(_projects())
+
+
+# ─── Config ───────────────────────────────────────────────────────────
+
+@app.command()
+def config(
+    key: Optional[str] = typer.Argument(None, help="Setting key"),
+    value: Optional[str] = typer.Argument(None, help="Setting value"),
+):
+    """View or set configuration."""
+    settings = get_settings()
+    if key and value:
+        if hasattr(settings, key):
+            setattr(settings, key, value)
+            save_settings(settings)
+            console.print(f"[green]Set {key} = {value}[/green]")
+        else:
+            console.print(f"[red]Unknown setting: {key}[/red]")
+    else:
+        table = Table(title="Configuration")
+        table.add_column("Key", style="cyan")
+        table.add_column("Value")
+        for k, v in settings.model_dump().items():
+            table.add_row(k, str(v))
+        table.add_row("authenticated", str(bool(get_token())))
+        console.print(table)
+
+
+# ─── Local Project Operations (no server needed) ─────────────────────
+
+@app.command()
+def context(
+    path: str = typer.Argument(".", help="Project directory"),
+    patterns: Optional[str] = typer.Option(None, help="Glob patterns (comma-separated)"),
+    max_files: int = typer.Option(30, help="Max files to include"),
+    output: Optional[str] = typer.Option(None, "-o", help="Save context to file"),
+):
+    """Scan a local project and build LLM-ready context.
+
+    This runs locally — no server needed. Use this to load any codebase
+    into a context block you can paste into chat or pipe to 'msapling chat'.
+    """
+    from .local import detect_project_root, build_file_tree, read_files_as_context
+
+    root, info = detect_project_root(path)
+    console.print(f"[cyan]Project root:[/cyan] {root}")
+    console.print(f"[cyan]Type:[/cyan] {info['type']} | Markers: {', '.join(info['markers'])}")
+
+    pattern_list = patterns.split(",") if patterns else None
+    files = build_file_tree(root, patterns=pattern_list, max_files=max_files)
+    console.print(f"[cyan]Files found:[/cyan] {len(files)}")
+
+    context_block = read_files_as_context(root, files)
+    token_est = len(context_block) // 4
+    console.print(f"[cyan]Context size:[/cyan] ~{token_est:,} tokens ({len(context_block):,} chars)")
+
+    if output:
+        Path(output).write_text(context_block, encoding="utf-8")
+        console.print(f"[green]Saved to {output}[/green]")
+    else:
+        console.print(Panel(
+            f"[dim]{context_block[:500]}...[/dim]" if len(context_block) > 500 else context_block,
+            title="Context Preview (first 500 chars)",
+        ))
+        console.print(f"\n[yellow]Use -o context.md to save full context, or pipe to chat:[/yellow]")
+        console.print(f"  msapling context . -o ctx.md && msapling chat -i")
+
+
+@app.command()
+def git(
+    args: str = typer.Argument(..., help="Git arguments (e.g. 'status', 'log --oneline -5')"),
+    cwd: str = typer.Option(".", help="Working directory"),
+):
+    """Run git commands locally with pretty output."""
+    from .local import git_status, git_diff, git_log
+    import subprocess
+
+    parts = args.split()
+    subcmd = parts[0] if parts else ""
+
+    # Shortcuts for common commands
+    if subcmd == "s":
+        console.print(Syntax(git_status(cwd), "diff", theme="monokai"))
+        return
+    if subcmd == "d":
+        console.print(Syntax(git_diff(cwd), "diff", theme="monokai"))
+        return
+    if subcmd == "l":
+        console.print(git_log(cwd))
+        return
+
+    try:
+        result = subprocess.run(
+            ["git"] + parts,
+            cwd=cwd, capture_output=True, text=True, timeout=30,
+        )
+        if result.stdout:
+            if subcmd in ("diff", "show", "log"):
+                console.print(Syntax(result.stdout, "diff", theme="monokai"))
+            else:
+                console.print(result.stdout)
+        if result.stderr and result.returncode != 0:
+            console.print(f"[red]{result.stderr}[/red]")
+    except subprocess.TimeoutExpired:
+        console.print("[red]Git command timed out (30s)[/red]")
+    except FileNotFoundError:
+        console.print("[red]Git not found — install git first[/red]")
+
+
+@app.command()
+def scan(
+    path: str = typer.Argument(".", help="Directory to scan"),
+):
+    """Detect project type, language, framework, and file stats."""
+    from .local import detect_project_root, build_file_tree
+
+    root, info = detect_project_root(path)
+    files = build_file_tree(root, max_files=500)
+
+    # Count by extension
+    ext_counts: dict = {}
+    for f in files:
+        ext = Path(f["path"]).suffix or "(no ext)"
+        ext_counts[ext] = ext_counts.get(ext, 0) + 1
+
+    table = Table(title=f"Project: {Path(root).name}")
+    table.add_column("Property", style="cyan")
+    table.add_column("Value")
+    table.add_row("Root", root)
+    table.add_row("Type", info["type"])
+    table.add_row("Markers", ", ".join(info["markers"]) or "none")
+    table.add_row("Total Files", str(len(files)))
+    table.add_row("Total Lines", f"{sum(f['lines'] for f in files):,}")
+    console.print(table)
+
+    if ext_counts:
+        ext_table = Table(title="File Types")
+        ext_table.add_column("Extension", style="cyan")
+        ext_table.add_column("Count", justify="right")
+        for ext, count in sorted(ext_counts.items(), key=lambda x: -x[1])[:15]:
+            ext_table.add_row(ext, str(count))
+        console.print(ext_table)
+
+
+@app.command()
+def shell(
+    model: Optional[str] = typer.Option(None, "-m", help="Model ID"),
+    project: Optional[str] = typer.Option(None, "-p", help="Project name"),
+    resume: Optional[str] = typer.Option(None, "--resume", "-r", help="Resume session (ID or number)"),
+):
+    """Start interactive shell (like Claude Code / Gemini CLI).
+
+    Full-featured coding environment with slash commands:
+      /help, /model, /cost, /read, /grep, /run, /git, /plan, /save, /resume
+
+    Examples:
+      msapling shell                    # start new session
+      msapling shell -m gpt-4o          # with specific model
+      msapling shell --resume           # resume last session
+      msapling shell -r 1               # resume session #1
+    """
+    from .shell import run_shell
+    _run(run_shell(model=model, project=project, resume_id=resume))
+
+
+@app.command(name="mcp-serve")
+def mcp_serve():
+    """Start MSapling as an MCP server (for Claude Code, Cursor, etc).
+
+    This runs as a subprocess that communicates via stdin/stdout using
+    the Model Context Protocol. Add to your tool's MCP config:
+
+    Claude Code (~/.claude/settings.json):
+      "mcpServers": { "msapling": { "command": "msapling", "args": ["mcp-serve"] } }
+
+    Cursor (.cursor/mcp.json):
+      { "msapling": { "command": "msapling", "args": ["mcp-serve"] } }
+    """
+    from .mcp.server import serve
+    serve()
+
+
+@app.command()
+def benchmark(
+    prompt: str = typer.Argument("Explain the difference between a stack and a queue.", help="Prompt to benchmark"),
+    models: str = typer.Option(
+        "google/gemini-2.0-flash-001,anthropic/claude-3-haiku,openai/gpt-4o-mini",
+        "-m", help="Comma-separated model IDs to compare",
+    ),
+):
+    """Run a model benchmark from the CLI. Compares speed, cost, and quality.
+
+    Sends the same prompt to multiple models and shows results side-by-side
+    with tokens/sec, cost, and response preview.
+
+    Example:
+        msapling benchmark "explain recursion" -m "gpt-4o,claude-3.5-sonnet,gemini-flash"
+    """
+    from .completer import resolve_model
+    user = _get_user_or_exit()
+    require_pro(user, "benchmark")
+    model_list = [resolve_model(m.strip())[0] for m in models.split(",") if m.strip()]
+
+    async def _benchmark():
+        import time as _time
+        client = MSaplingClient()
+        try:
+            results = []
+            for mid in model_list:
+                model_short = mid.split("/")[-1] if "/" in mid else mid
+                with Status(f"Running {model_short}...", console=console):
+                    t0 = _time.monotonic()
+                    parts = []
+                    total_tokens = 0
+                    cost = 0.0
+                    try:
+                        async for chunk in client.stream_chat(
+                            chat_id=str(uuid.uuid4()),
+                            prompt=prompt,
+                            model=mid,
+                        ):
+                            content = chunk.get("content", "")
+                            if content:
+                                parts.append(content)
+                            if chunk.get("type") == "usage":
+                                usage = chunk.get("usage", {})
+                                total_tokens = usage.get("total_tokens", 0)
+                                cost = float(chunk.get("cost", 0))
+                        elapsed = _time.monotonic() - t0
+                        tps = total_tokens / elapsed if elapsed > 0 else 0
+                        results.append({
+                            "model": mid, "response": "".join(parts),
+                            "tokens": total_tokens, "cost": cost,
+                            "elapsed": elapsed, "tps": tps, "status": "ok",
+                        })
+                    except Exception as e:
+                        results.append({
+                            "model": mid, "response": "", "tokens": 0,
+                            "cost": 0, "elapsed": 0, "tps": 0,
+                            "status": f"error: {e}",
+                        })
+
+            # Results table
+            table = Table(title="Benchmark Results")
+            table.add_column("Model", style="cyan")
+            table.add_column("Tokens", justify="right")
+            table.add_column("TPS", justify="right")
+            table.add_column("Cost", justify="right")
+            table.add_column("Time", justify="right")
+            table.add_column("Status")
+            for r in sorted(results, key=lambda x: x["tps"], reverse=True):
+                model_short = r["model"].split("/")[-1] if "/" in r["model"] else r["model"]
+                status_color = "green" if r["status"] == "ok" else "red"
+                table.add_row(
+                    model_short,
+                    f"{r['tokens']:,}",
+                    f"{r['tps']:.1f}",
+                    f"${r['cost']:.4f}",
+                    f"{r['elapsed']:.1f}s",
+                    f"[{status_color}]{r['status']}[/{status_color}]",
+                )
+            console.print(table)
+
+            # Show responses
+            for r in results:
+                if r["response"]:
+                    model_short = r["model"].split("/")[-1] if "/" in r["model"] else r["model"]
+                    console.print(Panel(
+                        Markdown(r["response"][:2000]),
+                        title=f"[cyan]{model_short}[/cyan] ({r['tokens']:,} tok, {r['tps']:.1f} tok/s)",
+                        border_style="cyan" if r["status"] == "ok" else "red",
+                    ))
+        except Exception as e:
+            console.print(f"[red]Benchmark failed: {e}[/red]")
+        finally:
+            await client.close()
+
+    _run(_benchmark())
+
+
+@app.command()
+def completions(
+    shell_name: str = typer.Argument("bash", help="Shell: bash, zsh, fish, powershell"),
+    install: bool = typer.Option(False, "--install", help="Install completions to shell profile"),
+):
+    """Generate or install shell tab completions.
+
+    Examples:
+        msapling completions bash --install
+        msapling completions zsh >> ~/.zshrc
+        msapling completions fish > ~/.config/fish/completions/msapling.fish
+        msapling completions powershell >> $PROFILE
+    """
+    import subprocess as _sp
+    shell_map = {"bash": "bash", "zsh": "zsh", "fish": "fish", "powershell": "powershell", "pwsh": "powershell"}
+    target = shell_map.get(shell_name.lower())
+    if not target:
+        console.print(f"[red]Unknown shell: {shell_name}. Options: bash, zsh, fish, powershell[/red]")
+        raise typer.Exit(1)
+
+    if install:
+        try:
+            # Use typer's built-in completion installer
+            import typer.completion as _tc
+            _tc.install(shell=target)
+            console.print(f"[green]Completions installed for {target}.[/green]")
+        except Exception:
+            console.print(f"[yellow]Auto-install not available. Generate manually:[/yellow]")
+            console.print(f"  msapling completions {shell_name} >> <your-shell-profile>")
+    else:
+        try:
+            result = _sp.run(
+                [sys.executable, "-m", "msapling_cli.main"],
+                env={**os.environ, "_MSAPLING_COMPLETE": f"complete_{target}"},
+                capture_output=True, text=True,
+            )
+            if result.stdout:
+                print(result.stdout)
+            else:
+                console.print(f"[dim]Completion script for {target} (pipe to your shell profile).[/dim]")
+        except Exception as e:
+            console.print(f"[red]{e}[/red]")
+
+
+@app.command()
+def doctor():
+    """Diagnose installation, auth, and connectivity."""
+    import shutil
+
+    console.print("[bold]MSapling Doctor[/bold]")
+    console.print()
+
+    # Python
+    console.print(f"  Python:     {sys.version.split()[0]}")
+
+    # Dependencies
+    for pkg in ["httpx", "rich", "typer", "pydantic"]:
+        try:
+            mod = __import__(pkg)
+            ver = getattr(mod, "__version__", "?")
+            console.print(f"  {pkg:12s} {ver} [green]OK[/green]")
+        except ImportError:
+            console.print(f"  {pkg:12s} [red]MISSING[/red]")
+
+    # Git
+    git_path = shutil.which("git")
+    console.print(f"  git:        {'[green]' + git_path + '[/green]' if git_path else '[red]NOT FOUND[/red]'}")
+
+    # ripgrep
+    rg_path = shutil.which("rg")
+    console.print(f"  ripgrep:    {'[green]' + rg_path + '[/green]' if rg_path else '[yellow]not found (grep fallback)[/yellow]'}")
+
+    # Auth
+    token = get_token()
+    console.print(f"  Auth token: {'[green]present[/green]' if token else '[red]missing (run: msapling login)[/red]'}")
+
+    # API connectivity
+    async def _check():
+        client = MSaplingClient()
+        try:
+            ok = await client.health_check()
+            return ok
+        finally:
+            await client.close()
+
+    try:
+        api_ok = _run(_check())
+        console.print(f"  API:        {'[green]reachable[/green]' if api_ok else '[red]unreachable[/red]'}")
+    except Exception:
+        console.print(f"  API:        [red]unreachable[/red]")
+
+    # Config
+    settings = get_settings()
+    console.print(f"  API URL:    {settings.api_url}")
+    console.print(f"  Model:      {settings.default_model}")
+    console.print()
+
+
+@app.command()
+def version():
+    """Show version."""
+    console.print(f"msapling-cli v{__version__}")
+
+
+if __name__ == "__main__":
+    app()