treadstone-cli 0.2.1__py3-none-any.whl

treadstone_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m treadstone_cli` and PyInstaller builds."""
+
+from treadstone_cli.main import cli
+
+if __name__ == "__main__":
+    cli()

treadstone_cli/_client.py

@@ -0,0 +1,77 @@
+"""HTTP client factory for CLI commands.
+
+Priority: CLI flags > environment variables > config file.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import click
+import httpx
+
+CONFIG_DIR = Path.home() / ".config" / "treadstone"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+
+_DEFAULT_BASE_URL = "https://api.treadstone-ai.dev"
+
+
+def _read_config() -> dict[str, str]:
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        import tomllib
+    except ModuleNotFoundError:
+        import tomli as tomllib  # type: ignore[no-redef]
+    with open(CONFIG_FILE, "rb") as f:
+        data = tomllib.load(f)
+    return data.get("default", {})
+
+
+def get_base_url(ctx: click.Context) -> str:
+    url = ctx.obj.get("base_url") or _read_config().get("base_url") or _DEFAULT_BASE_URL
+    return url.rstrip("/")
+
+
+def get_api_key(ctx: click.Context) -> str | None:
+    return ctx.obj.get("api_key") or _read_config().get("api_key")
+
+
+def effective_base_url() -> tuple[str, str]:
+    """Return (url, source) without requiring a Click context.
+
+    Source is one of: 'env', 'file', 'default'.
+    Used for displaying configuration in help text.
+    """
+    env = os.environ.get("TREADSTONE_BASE_URL")
+    if env:
+        return env.rstrip("/"), "env"
+    cfg = _read_config().get("base_url")
+    if cfg:
+        return cfg.rstrip("/"), "file"
+    return _DEFAULT_BASE_URL, "default"
+
+
+def effective_api_key() -> str | None:
+    """Return API key without requiring a Click context."""
+    return os.environ.get("TREADSTONE_API_KEY") or _read_config().get("api_key")
+
+
+def build_client(ctx: click.Context) -> httpx.Client:
+    base_url = get_base_url(ctx)
+    api_key = get_api_key(ctx)
+    headers: dict[str, str] = {}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return httpx.Client(base_url=base_url, headers=headers, timeout=30.0)
+
+
+def require_auth(ctx: click.Context) -> httpx.Client:
+    """Build client and abort if no API key is configured."""
+    client = build_client(ctx)
+    if "Authorization" not in client.headers:
+        click.echo("Error: No API key configured. Set TREADSTONE_API_KEY or use --api-key.", err=True)
+        sys.exit(1)
+    return client

treadstone_cli/_output.py

@@ -0,0 +1,102 @@
+"""Output formatting utilities for CLI — table (Rich) or JSON mode."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import click
+import httpx
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def friendly_exception_handler(cli_main: click.Group) -> click.Group:
+    """Wrap a Click group so unhandled exceptions print user-friendly messages instead of tracebacks."""
+    original_main = cli_main.main
+
+    def _patched_main(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return original_main(*args, standalone_mode=False, **kwargs)
+        except click.exceptions.Abort:
+            click.echo("\nAborted.", err=True)
+            sys.exit(130)
+        except click.exceptions.Exit as exc:
+            sys.exit(exc.exit_code)
+        except click.UsageError as exc:
+            exc.show()
+            sys.exit(exc.exit_code if exc.exit_code is not None else 2)
+        except SystemExit:
+            raise
+        except KeyboardInterrupt:
+            click.echo("\nInterrupted.", err=True)
+            sys.exit(130)
+        except httpx.ConnectError as exc:
+            _print_network_hint(str(exc), "Connection refused")
+            sys.exit(1)
+        except httpx.TimeoutException:
+            click.echo("Error: Request timed out. The server may be slow or unreachable.", err=True)
+            sys.exit(1)
+        except httpx.HTTPStatusError as exc:
+            click.echo(f"Error: HTTP {exc.response.status_code} — {exc.response.text[:200]}", err=True)
+            sys.exit(1)
+        except httpx.HTTPError as exc:
+            click.echo(f"Error: {type(exc).__name__} — {exc}", err=True)
+            sys.exit(1)
+        except Exception as exc:
+            click.echo(f"Error: {exc}", err=True)
+            sys.exit(1)
+
+    cli_main.main = _patched_main  # type: ignore[assignment]
+    return cli_main
+
+
+def _print_network_hint(detail: str, summary: str) -> None:
+    click.echo(f"Error: {summary}.", err=True)
+    click.echo("  Possible causes:", err=True)
+    click.echo("    - The Treadstone server is not running", err=True)
+    click.echo("    - The --base-url or TREADSTONE_BASE_URL is incorrect", err=True)
+    click.echo("    - A firewall or proxy is blocking the connection", err=True)
+    click.echo(f"  Detail: {detail}", err=True)
+
+
+def is_json_mode(ctx: click.Context) -> bool:
+    return ctx.obj.get("json_output", False)
+
+
+def print_json(data: Any) -> None:
+    click.echo(json.dumps(data, indent=2, default=str))
+
+
+def print_table(columns: list[str], rows: list[list[Any]], title: str | None = None) -> None:
+    table = Table(title=title, show_header=True, header_style="bold cyan")
+    for col in columns:
+        table.add_column(col)
+    for row in rows:
+        table.add_row(*[str(v) if v is not None else "" for v in row])
+    console.print(table)
+
+
+def print_detail(data: dict[str, Any], title: str | None = None) -> None:
+    table = Table(title=title, show_header=False)
+    table.add_column("Field", style="bold")
+    table.add_column("Value")
+    for k, v in data.items():
+        table.add_row(k, str(v) if v is not None else "")
+    console.print(table)
+
+
+def handle_error(resp: Any) -> None:
+    """Print error and exit if response is not 2xx."""
+    if resp.status_code >= 400:
+        try:
+            body = resp.json()
+            err = body.get("error", body)
+            msg = err.get("message", str(err)) if isinstance(err, dict) else str(err)
+        except Exception:
+            msg = resp.text
+        click.echo(f"Error ({resp.status_code}): {msg}", err=True)
+        sys.exit(1)

treadstone_cli/api_keys.py

@@ -0,0 +1,73 @@
+"""API key management commands."""
+
+from __future__ import annotations
+
+import click
+
+from treadstone_cli._client import require_auth
+from treadstone_cli._output import handle_error, is_json_mode, print_json, print_table
+
+
+@click.group()
+def api_keys() -> None:
+    """Manage API keys.
+
+    API keys provide long-lived authentication tokens for programmatic access.
+
+    \b
+    Examples:
+      treadstone api-keys create --name ci-bot
+      treadstone api-keys list
+      treadstone api-keys delete <key-id>
+    """
+
+
+@api_keys.command("create")
+@click.option("--name", default="default", help="Key name.")
+@click.option("--expires-in", default=None, type=int, help="Key lifetime in seconds.")
+@click.pass_context
+def create_key(ctx: click.Context, name: str, expires_in: int | None) -> None:
+    """Create a new API key.
+
+    The full key is shown only once — store it securely.
+    """
+    client = require_auth(ctx)
+    body: dict = {"name": name}
+    if expires_in is not None:
+        body["expires_in"] = expires_in
+    resp = client.post("/v1/auth/api-keys", json=body)
+    handle_error(resp)
+    data = resp.json()
+    if is_json_mode(ctx):
+        print_json(data)
+    else:
+        click.echo(f"API Key created: {data['key']}")
+        click.echo(f"  ID: {data['id']}  Name: {data['name']}")
+        click.echo("  Store this key securely — it won't be shown again.")
+
+
+@api_keys.command("list")
+@click.pass_context
+def list_keys(ctx: click.Context) -> None:
+    """List all API keys for the current user."""
+    client = require_auth(ctx)
+    resp = client.get("/v1/auth/api-keys")
+    handle_error(resp)
+    data = resp.json()
+    if is_json_mode(ctx):
+        print_json(data)
+    else:
+        items = data.get("items", [])
+        rows = [[k["id"], k["name"], k["key_prefix"], k.get("created_at", ""), k.get("expires_at", "")] for k in items]
+        print_table(["ID", "Name", "Key Prefix", "Created", "Expires"], rows, title="API Keys")
+
+
+@api_keys.command("delete")
+@click.argument("key_id")
+@click.pass_context
+def delete_key(ctx: click.Context, key_id: str) -> None:
+    """Revoke and delete an API key."""
+    client = require_auth(ctx)
+    resp = client.delete(f"/v1/auth/api-keys/{key_id}")
+    handle_error(resp)
+    click.echo(f"API key {key_id} deleted.")

treadstone_cli/auth.py

@@ -0,0 +1,153 @@
+"""Auth commands — login, logout, register, whoami, change-password, invite, users, delete-user."""
+
+from __future__ import annotations
+
+import click
+
+from treadstone_cli._client import build_client, require_auth
+from treadstone_cli._output import handle_error, is_json_mode, print_detail, print_json, print_table
+
+
+@click.group()
+def auth() -> None:
+    """Authentication and user management.
+
+    Register, log in, manage users, and change passwords.
+
+    \b
+    Quick start:
+      treadstone auth register          Create a new account
+      treadstone auth login             Log in (saves session)
+      treadstone auth whoami            Verify current identity
+    """
+
+
+@auth.command("login")
+@click.option("--email", required=True, prompt=True, help="Account email.")
+@click.option("--password", required=True, prompt=True, hide_input=True, help="Account password.")
+@click.pass_context
+def login(ctx: click.Context, email: str, password: str) -> None:
+    """Log in with email and password.
+
+    If --email or --password are not provided, you will be prompted interactively.
+    """
+    client = build_client(ctx)
+    resp = client.post("/v1/auth/login", json={"email": email, "password": password})
+    handle_error(resp)
+    data = resp.json()
+    if is_json_mode(ctx):
+        print_json(data)
+    else:
+        click.echo("Login successful.")
+
+
+@auth.command("logout")
+@click.pass_context
+def logout(ctx: click.Context) -> None:
+    """Log out (clear session cookie)."""
+    client = build_client(ctx)
+    resp = client.post("/v1/auth/logout")
+    handle_error(resp)
+    if is_json_mode(ctx):
+        print_json(resp.json())
+    else:
+        click.echo("Logged out.")
+
+
+@auth.command("register")
+@click.option("--email", required=True, prompt=True, help="Account email.")
+@click.option("--password", required=True, prompt=True, hide_input=True, confirmation_prompt=True, help="Password.")
+@click.option("--invitation-token", default=None, help="Invitation token (required in invitation mode).")
+@click.pass_context
+def register(ctx: click.Context, email: str, password: str, invitation_token: str | None) -> None:
+    """Register a new account.
+
+    In invitation-only mode, an --invitation-token is required.
+    """
+    client = build_client(ctx)
+    body: dict = {"email": email, "password": password}
+    if invitation_token:
+        body["invitation_token"] = invitation_token
+    resp = client.post("/v1/auth/register", json=body)
+    handle_error(resp)
+    data = resp.json()
+    if is_json_mode(ctx):
+        print_json(data)
+    else:
+        click.echo(f"Registered: {data['email']} (role: {data['role']})")
+
+
+@auth.command("whoami")
+@click.pass_context
+def whoami(ctx: click.Context) -> None:
+    """Show current user info."""
+    client = require_auth(ctx)
+    resp = client.get("/v1/auth/user")
+    handle_error(resp)
+    data = resp.json()
+    if is_json_mode(ctx):
+        print_json(data)
+    else:
+        print_detail(data, title="Current User")
+
+
+@auth.command("change-password")
+@click.option("--old-password", required=True, prompt=True, hide_input=True, help="Current password.")
+@click.option(
+    "--new-password", required=True, prompt=True, hide_input=True, confirmation_prompt=True, help="New password."
+)
+@click.pass_context
+def change_password(ctx: click.Context, old_password: str, new_password: str) -> None:
+    """Change your password."""
+    client = require_auth(ctx)
+    resp = client.post("/v1/auth/change-password", json={"old_password": old_password, "new_password": new_password})
+    handle_error(resp)
+    if is_json_mode(ctx):
+        print_json(resp.json())
+    else:
+        click.echo("Password changed.")
+
+
+@auth.command("invite")
+@click.option("--email", required=True, help="Email of the person to invite.")
+@click.option("--role", default="ro", help="Role for the invitee (admin or ro).")
+@click.pass_context
+def invite(ctx: click.Context, email: str, role: str) -> None:
+    """Generate an invitation token for a new user (admin only)."""
+    client = require_auth(ctx)
+    resp = client.post("/v1/auth/invite", json={"email": email, "role": role})
+    handle_error(resp)
+    data = resp.json()
+    if is_json_mode(ctx):
+        print_json(data)
+    else:
+        click.echo(f"Invitation sent to {data['email']}. Token: {data['token']}")
+
+
+@auth.command("users")
+@click.option("--limit", default=100, type=int, help="Max results.")
+@click.option("--offset", default=0, type=int, help="Skip N results.")
+@click.pass_context
+def list_users(ctx: click.Context, limit: int, offset: int) -> None:
+    """List all registered users (admin only)."""
+    client = require_auth(ctx)
+    resp = client.get("/v1/auth/users", params={"limit": limit, "offset": offset})
+    handle_error(resp)
+    data = resp.json()
+    if is_json_mode(ctx):
+        print_json(data)
+    else:
+        items = data.get("items", [])
+        rows = [[u["id"], u["email"], u["role"]] for u in items]
+        print_table(["ID", "Email", "Role"], rows, title=f"Users ({data['total']} total)")
+
+
+@auth.command("delete-user")
+@click.argument("user_id")
+@click.pass_context
+def delete_user(ctx: click.Context, user_id: str) -> None:
+    """Delete a user (admin only)."""
+    client = require_auth(ctx)
+    resp = client.delete(f"/v1/auth/users/{user_id}")
+    handle_error(resp)
+    click.echo(f"User {user_id} deleted.")

treadstone_cli/config_cmd.py

@@ -0,0 +1,157 @@
+"""Local CLI configuration commands.
+
+Manages ~/.config/treadstone/config.toml which stores defaults for
+base_url, api_key, and other settings so they don't need to be passed
+as flags or env vars every time.
+"""
+
+from __future__ import annotations
+
+import click
+
+from treadstone_cli._client import CONFIG_DIR, CONFIG_FILE, _read_config
+
+
+def _write_config(data: dict[str, dict[str, str]]) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    lines: list[str] = []
+    for section, kvs in data.items():
+        lines.append(f"[{section}]")
+        for k, v in kvs.items():
+            lines.append(f'{k} = "{v}"')
+        lines.append("")
+    CONFIG_FILE.write_text("\n".join(lines))
+
+
+_VALID_KEYS = ("base_url", "api_key")
+
+
+@click.group()
+def config() -> None:
+    """Manage local CLI configuration.
+
+    Configuration is stored in ~/.config/treadstone/config.toml and provides
+    default values for --base-url and --api-key so they don't need to be
+    repeated on every command invocation.
+
+    \b
+    Priority (highest to lowest):
+      1. CLI flags   (--base-url, --api-key)
+      2. Env vars    (TREADSTONE_BASE_URL, TREADSTONE_API_KEY)
+      3. Config file (~/.config/treadstone/config.toml)
+    """
+
+
+@config.command("set")
+@click.argument("key", type=click.Choice(_VALID_KEYS, case_sensitive=False))
+@click.argument("value")
+def set_value(key: str, value: str) -> None:
+    """Set a configuration value.
+
+    \b
+    Available keys:
+      base_url   Base URL of the Treadstone server
+      api_key    Default API key for authentication
+
+    \b
+    Examples:
+      treadstone config set base_url https://my-server.example.com
+      treadstone config set api_key ts_live_xxxxxxxxxxxx
+    """
+    try:
+        import tomllib
+    except ModuleNotFoundError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+    raw: dict[str, dict[str, str]] = {}
+    if CONFIG_FILE.exists():
+        with open(CONFIG_FILE, "rb") as f:
+            raw = tomllib.load(f)  # type: ignore[assignment]
+
+    section = raw.setdefault("default", {})
+    section[key] = value
+    _write_config(raw)
+    click.echo(f"Set {key} = {value}")
+
+
+@config.command("get")
+@click.argument("key", required=False, default=None)
+def get_value(key: str | None) -> None:
+    """Get a configuration value (or all values if no key given).
+
+    \b
+    Examples:
+      treadstone config get              Show all config values
+      treadstone config get base_url     Show only base_url
+    """
+    data = _read_config()
+    if not data:
+        click.echo("No configuration set. Run 'treadstone config set <key> <value>' to get started.")
+        return
+
+    if key is not None:
+        if key not in _VALID_KEYS:
+            click.echo(f"Error: Unknown key '{key}'. Valid keys: {', '.join(_VALID_KEYS)}", err=True)
+            raise SystemExit(1)
+        val = data.get(key)
+        if val is None:
+            click.echo(f"{key} is not set.")
+        else:
+            display = _mask_secret(key, val)
+            click.echo(f"{key} = {display}")
+    else:
+        for k in _VALID_KEYS:
+            val = data.get(k)
+            if val is not None:
+                click.echo(f"{k} = {_mask_secret(k, val)}")
+
+
+@config.command("unset")
+@click.argument("key", type=click.Choice(_VALID_KEYS, case_sensitive=False))
+def unset_value(key: str) -> None:
+    """Remove a configuration value.
+
+    \b
+    Example:
+      treadstone config unset api_key
+    """
+    try:
+        import tomllib
+    except ModuleNotFoundError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+    if not CONFIG_FILE.exists():
+        click.echo(f"{key} is not set.")
+        return
+
+    with open(CONFIG_FILE, "rb") as f:
+        raw: dict[str, dict[str, str]] = tomllib.load(f)  # type: ignore[assignment]
+
+    section = raw.get("default", {})
+    if key not in section:
+        click.echo(f"{key} is not set.")
+        return
+
+    del section[key]
+    _write_config(raw)
+    click.echo(f"Unset {key}.")
+
+
+@config.command("path")
+def show_path() -> None:
+    """Print the path to the configuration file.
+
+    \b
+    Example:
+      treadstone config path
+    """
+    exists = CONFIG_FILE.exists()
+    click.echo(str(CONFIG_FILE))
+    if not exists:
+        click.echo("  (file does not exist yet)")
+
+
+def _mask_secret(key: str, value: str) -> str:
+    if key == "api_key" and len(value) > 8:
+        return value[:8] + "..." + value[-4:]
+    return value

treadstone_cli/main.py

@@ -0,0 +1,104 @@
+"""Treadstone CLI — agent-native sandbox management."""
+
+from __future__ import annotations
+
+import click
+
+from treadstone_cli._client import build_client, effective_api_key, effective_base_url, get_base_url
+from treadstone_cli._output import friendly_exception_handler, handle_error, is_json_mode, print_json
+
+_STATIC_EPILOG = """\b
+Configuration (highest to lowest priority):
+  CLI flags       --api-key, --base-url
+  Env vars        TREADSTONE_API_KEY, TREADSTONE_BASE_URL
+  Config file     ~/.config/treadstone/config.toml
+
+  Run 'treadstone config --help' to manage the config file.
+
+Examples:
+  treadstone health                         Check server status
+  treadstone sandboxes list                 List running sandboxes
+  treadstone sb create --template default   Create a sandbox
+  treadstone auth login                     Log in with email/password
+"""
+
+
+class _TreadstoneGroup(click.Group):
+    """Custom group that appends a live config summary to the help output."""
+
+    def format_epilog(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        super().format_epilog(ctx, formatter)
+        url, source = effective_base_url()
+        api_key = effective_api_key()
+        api_key_status = "configured" if api_key else "not set"
+        with formatter.section("Active configuration"):
+            formatter.write_dl(
+                [
+                    ("Base URL", f"{url}  [{source}]"),
+                    ("API key", api_key_status),
+                ]
+            )
+
+
+@click.group(cls=_TreadstoneGroup, epilog=_STATIC_EPILOG)
+@click.option("--json", "json_output", is_flag=True, default=False, help="Output in JSON format.")
+@click.option(
+    "--api-key",
+    envvar="TREADSTONE_API_KEY",
+    default=None,
+    help="API key for authentication (env: TREADSTONE_API_KEY).",
+)
+@click.option(
+    "--base-url",
+    envvar="TREADSTONE_BASE_URL",
+    default=None,
+    help="Base URL of the Treadstone server (env: TREADSTONE_BASE_URL).",
+)
+@click.version_option(package_name="treadstone-cli")
+@click.pass_context
+def cli(ctx: click.Context, json_output: bool, api_key: str | None, base_url: str | None) -> None:
+    """Treadstone CLI — manage sandboxes, templates, and API keys.
+
+    An agent-native sandbox service. Run code, build projects, and deploy
+    environments via the command line.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["json_output"] = json_output
+    if api_key:
+        ctx.obj["api_key"] = api_key
+    if base_url:
+        ctx.obj["base_url"] = base_url
+
+
+@cli.command()
+@click.pass_context
+def health(ctx: click.Context) -> None:
+    """Check if the Treadstone server is reachable and healthy."""
+    client = build_client(ctx)
+    base_url = get_base_url(ctx)
+    if not is_json_mode(ctx):
+        click.echo(f"Connecting to {base_url} ...")
+    resp = client.get("/health")
+    handle_error(resp)
+    data = resp.json()
+    if is_json_mode(ctx):
+        print_json(data)
+    else:
+        status = data.get("status", "unknown")
+        click.echo(f"Server is {status}")
+
+
+from treadstone_cli.api_keys import api_keys  # noqa: E402
+from treadstone_cli.auth import auth  # noqa: E402
+from treadstone_cli.config_cmd import config  # noqa: E402
+from treadstone_cli.sandboxes import sandboxes  # noqa: E402
+from treadstone_cli.templates import templates  # noqa: E402
+
+cli.add_command(auth)
+cli.add_command(api_keys, "api-keys")
+cli.add_command(sandboxes)
+cli.add_command(sandboxes, "sb")
+cli.add_command(templates)
+cli.add_command(config)
+
+friendly_exception_handler(cli)

treadstone_cli/sandboxes.py

@@ -0,0 +1,170 @@
+"""Sandbox management commands."""
+
+from __future__ import annotations
+
+import click
+
+from treadstone_cli._client import require_auth
+from treadstone_cli._output import handle_error, is_json_mode, print_detail, print_json, print_table
+
+
+@click.group()
+def sandboxes() -> None:
+    """Manage sandboxes.
+
+    Create, list, start, stop, and delete sandboxes. Use 'sb' as a shorthand.
+
+    \b
+    Examples:
+      treadstone sandboxes create --template default --name my-box
+      treadstone sb list
+      treadstone sb get <sandbox-id>
+      treadstone sb delete <sandbox-id>
+    """
+
+
+@sandboxes.command("create")
+@click.option("--template", required=True, help="Sandbox template name.")
+@click.option("--name", default=None, help="Sandbox name (auto-generated if omitted).")
+@click.option("--label", multiple=True, help="Labels in key:val format (repeatable).")
+@click.option("--persist", is_flag=True, default=False, help="Enable persistent storage.")
+@click.option("--storage-size", default="10Gi", help="PVC size when --persist is set.")
+@click.pass_context
+def create(
+    ctx: click.Context,
+    template: str,
+    name: str | None,
+    label: tuple[str, ...],
+    persist: bool,
+    storage_size: str,
+) -> None:
+    """Create a new sandbox from a template.
+
+    \b
+    Examples:
+      treadstone sb create --template default
+      treadstone sb create --template python --name dev-box --label env:dev
+      treadstone sb create --template node --persist --storage-size 20Gi
+    """
+    client = require_auth(ctx)
+    labels = {}
+    for lbl in label:
+        if ":" not in lbl:
+            click.echo(f"Error: Invalid label format '{lbl}'. Use key:val.", err=True)
+            raise SystemExit(1)
+        k, v = lbl.split(":", 1)
+        labels[k] = v
+    body: dict = {"template": template, "labels": labels, "persist": persist, "storage_size": storage_size}
+    if name:
+        body["name"] = name
+    resp = client.post("/v1/sandboxes", json=body)
+    handle_error(resp)
+    data = resp.json()
+    if is_json_mode(ctx):
+        print_json(data)
+    else:
+        print_detail(data, title="Sandbox Created")
+
+
+@sandboxes.command("list")
+@click.option("--label", default=None, help="Filter by label (key:val).")
+@click.option("--limit", default=100, type=int, help="Max results.")
+@click.option("--offset", default=0, type=int, help="Skip N results.")
+@click.pass_context
+def list_sandboxes(ctx: click.Context, label: str | None, limit: int, offset: int) -> None:
+    """List sandboxes with optional filtering.
+
+    \b
+    Examples:
+      treadstone sb list
+      treadstone sb list --label env:prod --limit 10
+    """
+    client = require_auth(ctx)
+    params: dict = {"limit": limit, "offset": offset}
+    if label:
+        params["label"] = label
+    resp = client.get("/v1/sandboxes", params=params)
+    handle_error(resp)
+    data = resp.json()
+    if is_json_mode(ctx):
+        print_json(data)
+    else:
+        items = data.get("items", [])
+        rows = [[s["id"], s["name"], s["template"], s["status"], s.get("created_at", "")] for s in items]
+        print_table(["ID", "Name", "Template", "Status", "Created"], rows, title=f"Sandboxes ({data['total']} total)")
+
+
+@sandboxes.command("get")
+@click.argument("sandbox_id")
+@click.pass_context
+def get_sandbox(ctx: click.Context, sandbox_id: str) -> None:
+    """Show detailed information about a sandbox."""
+    client = require_auth(ctx)
+    resp = client.get(f"/v1/sandboxes/{sandbox_id}")
+    handle_error(resp)
+    data = resp.json()
+    if is_json_mode(ctx):
+        print_json(data)
+    else:
+        print_detail(data, title=f"Sandbox {sandbox_id}")
+
+
+@sandboxes.command("delete")
+@click.argument("sandbox_id")
+@click.pass_context
+def delete_sandbox(ctx: click.Context, sandbox_id: str) -> None:
+    """Delete a sandbox."""
+    client = require_auth(ctx)
+    resp = client.delete(f"/v1/sandboxes/{sandbox_id}")
+    handle_error(resp)
+    click.echo(f"Sandbox {sandbox_id} deleted.")
+
+
+@sandboxes.command("start")
+@click.argument("sandbox_id")
+@click.pass_context
+def start_sandbox(ctx: click.Context, sandbox_id: str) -> None:
+    """Start a stopped sandbox."""
+    client = require_auth(ctx)
+    resp = client.post(f"/v1/sandboxes/{sandbox_id}/start")
+    handle_error(resp)
+    data = resp.json()
+    if is_json_mode(ctx):
+        print_json(data)
+    else:
+        click.echo(f"Sandbox {sandbox_id} starting.")
+
+
+@sandboxes.command("stop")
+@click.argument("sandbox_id")
+@click.pass_context
+def stop_sandbox(ctx: click.Context, sandbox_id: str) -> None:
+    """Stop a running sandbox."""
+    client = require_auth(ctx)
+    resp = client.post(f"/v1/sandboxes/{sandbox_id}/stop")
+    handle_error(resp)
+    data = resp.json()
+    if is_json_mode(ctx):
+        print_json(data)
+    else:
+        click.echo(f"Sandbox {sandbox_id} stopping.")
+
+
+@sandboxes.command("token")
+@click.argument("sandbox_id")
+@click.option("--expires-in", default=3600, type=int, help="Token lifetime in seconds.")
+@click.pass_context
+def create_token(ctx: click.Context, sandbox_id: str, expires_in: int) -> None:
+    """Create a short-lived access token for a sandbox.
+
+    The token can be used to connect to the sandbox directly (e.g. via
+    WebSocket) without needing the main API key.
+    """
+    client = require_auth(ctx)
+    resp = client.post(f"/v1/sandboxes/{sandbox_id}/token", json={"expires_in": expires_in})
+    handle_error(resp)
+    data = resp.json()
+    if is_json_mode(ctx):
+        print_json(data)
+    else:
+        print_detail(data, title="Sandbox Token")

treadstone_cli/templates.py

@@ -0,0 +1,39 @@
+"""Sandbox template commands."""
+
+from __future__ import annotations
+
+import click
+
+from treadstone_cli._client import require_auth
+from treadstone_cli._output import handle_error, is_json_mode, print_json, print_table
+
+
+@click.group()
+def templates() -> None:
+    """Manage sandbox templates.
+
+    Templates define the runtime environment (image, CPU, memory) for sandboxes.
+
+    \b
+    Examples:
+      treadstone templates list
+    """
+
+
+@templates.command("list")
+@click.pass_context
+def list_templates(ctx: click.Context) -> None:
+    """List all available sandbox templates with resource specs."""
+    client = require_auth(ctx)
+    resp = client.get("/v1/sandbox-templates")
+    handle_error(resp)
+    data = resp.json()
+    if is_json_mode(ctx):
+        print_json(data)
+    else:
+        items = data.get("items", [])
+        rows = [
+            [t["name"], t["display_name"], t["resource_spec"]["cpu"], t["resource_spec"]["memory"], t["description"]]
+            for t in items
+        ]
+        print_table(["Name", "Display Name", "CPU", "Memory", "Description"], rows, title="Sandbox Templates")

treadstone_cli-0.2.1.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: treadstone-cli
+Version: 0.2.1
+Summary: CLI for the Treadstone sandbox service.
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: rich>=14.0
+Description-Content-Type: text/markdown
+
+# Treadstone CLI
+
+Command-line interface for the Treadstone sandbox service.
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install treadstone
+```
+
+### Pre-built binary
+
+Download the latest release from [GitHub Releases](https://github.com/earayu/treadstone/releases). The binary is self-contained and does not require Python.
+
+```bash
+# macOS / Linux
+chmod +x treadstone
+sudo mv treadstone /usr/local/bin/
+```
+
+## Quick start
+
+```bash
+# Check that the server is reachable
+treadstone health
+
+# Register an account (first time only)
+treadstone auth register
+
+# Log in
+treadstone auth login
+
+# Create an API key for non-interactive use
+treadstone api-keys create --name my-key
+# Save the key — it is shown only once
+
+# Store the key in config so you don't have to pass it every time
+treadstone config set api_key ts_live_xxxxxxxxxxxx
+
+# Create a sandbox
+treadstone sandboxes create --template default --name my-sandbox
+
+# List sandboxes
+treadstone sb list
+```
+
+## Configuration
+
+The CLI reads configuration from three sources, in order of priority:
+
+| Priority | Source | Example |
+|----------|--------|---------|
+| 1 (highest) | CLI flags | `--base-url https://... --api-key ts_...` |
+| 2 | Environment variables | `TREADSTONE_BASE_URL`, `TREADSTONE_API_KEY` |
+| 3 (lowest) | Config file | `~/.config/treadstone/config.toml` |
+
+### Config file
+
+Location: `~/.config/treadstone/config.toml`
+
+```toml
+[default]
+base_url = "https://your-server.example.com"
+api_key  = "ts_live_xxxxxxxxxxxx"
+```
+
+You can manage this file with the `config` subcommand:
+
+```bash
+# Set a value
+treadstone config set base_url https://your-server.example.com
+treadstone config set api_key ts_live_xxxxxxxxxxxx
+
+# View current settings (api_key is partially masked)
+treadstone config get
+
+# View a single key
+treadstone config get base_url
+
+# Remove a value
+treadstone config unset api_key
+
+# Show config file path
+treadstone config path
+```
+
+### Environment variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TREADSTONE_BASE_URL` | Base URL of the Treadstone server | `https://api.treadstone-ai.dev` |
+| `TREADSTONE_API_KEY` | API key for authentication | (none) |
+
+### Global flags
+
+| Flag | Description |
+|------|-------------|
+| `--base-url URL` | Override the server URL |
+| `--api-key KEY` | Override the API key |
+| `--json` | Output responses as JSON (useful for scripting) |
+| `--version` | Show CLI version |
+| `--help` | Show help message |
+
+## Commands
+
+### `health`
+
+Check if the server is reachable and healthy.
+
+```bash
+treadstone health
+# Server is healthy
+```
+
+### `auth`
+
+Authentication and user management.
+
+```bash
+treadstone auth register                 # Create a new account
+treadstone auth login                    # Log in interactively
+treadstone auth logout                   # Log out
+treadstone auth whoami                   # Show current user info
+treadstone auth change-password          # Change your password
+treadstone auth invite --email user@example.com   # Invite a user (admin)
+treadstone auth users                    # List all users (admin)
+treadstone auth delete-user <user-id>    # Delete a user (admin)
+```
+
+### `sandboxes` (alias: `sb`)
+
+Create and manage sandboxes.
+
+```bash
+treadstone sb create --template default --name my-box
+treadstone sb create --template python --label env:dev --persist
+treadstone sb list
+treadstone sb list --label env:prod --limit 10
+treadstone sb get <sandbox-id>
+treadstone sb start <sandbox-id>
+treadstone sb stop <sandbox-id>
+treadstone sb delete <sandbox-id>
+treadstone sb token <sandbox-id>                    # Get an access token
+treadstone sb token <sandbox-id> --expires-in 7200  # Custom TTL
+```
+
+### `templates`
+
+List available sandbox templates.
+
+```bash
+treadstone templates list
+```
+
+### `api-keys`
+
+Manage long-lived API keys.
+
+```bash
+treadstone api-keys create --name ci-bot
+treadstone api-keys create --name temp --expires-in 86400  # 24h
+treadstone api-keys list
+treadstone api-keys delete <key-id>
+```
+
+### `config`
+
+Manage local CLI configuration.
+
+```bash
+treadstone config set base_url https://...
+treadstone config set api_key ts_...
+treadstone config get
+treadstone config get base_url
+treadstone config unset api_key
+treadstone config path
+```
+
+## JSON output
+
+Pass `--json` before any command to get machine-readable JSON output:
+
+```bash
+treadstone --json sb list
+treadstone --json health
+treadstone --json api-keys list
+```
+
+## Error handling
+
+The CLI displays user-friendly error messages instead of stack traces:
+
+```
+Error: Connection refused.
+  Possible causes:
+    - The Treadstone server is not running
+    - The --base-url or TREADSTONE_BASE_URL is incorrect
+    - A firewall or proxy is blocking the connection
+  Detail: ...
+```
+
+Common errors:
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| Connection refused | Server not running or wrong URL | Check `treadstone config get base_url` |
+| Request timed out | Server slow or unreachable | Retry, or check network |
+| No API key configured | Missing authentication | `treadstone config set api_key <key>` |
+| HTTP 401 | Invalid or expired API key | Create a new key with `treadstone api-keys create` |
+| HTTP 404 | Resource not found | Verify the ID is correct |

treadstone_cli-0.2.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+treadstone_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+treadstone_cli/__main__.py,sha256=eR-fq48-urz4L6AhswpU2pJf7ZaQ2rtcH6XZF0s3_Fs,148
+treadstone_cli/_client.py,sha256=90xjZNjpWavW0qV2Y-WIbUrDnAnQR8sCt5LYPNi3mAY,2228
+treadstone_cli/_output.py,sha256=qfjz_7kMO6pJFuiftObgvxDGLvmv_uB9cqchk439PCE,3623
+treadstone_cli/api_keys.py,sha256=Otx-n5P3rTX6KxREphkuiGg6EUff_UvT7j3OluTm6y8,2285
+treadstone_cli/auth.py,sha256=cDnVBnBs_LW-MpB_G2ahlLk6nW_LN4JweAjq9xOxv5E,5349
+treadstone_cli/config_cmd.py,sha256=AlGxldd4GxahsbdOTIPSZ0Lq9JXfg3ZVWBqQAYtxbJ0,4421
+treadstone_cli/main.py,sha256=Wj6ILbjRuGLsgURnQhTty1r1y10aCweT64CTbBFkveI,3538
+treadstone_cli/sandboxes.py,sha256=-hSWyfvP-xiymIDCxPdUnYPeaDtIEhnMZu1wWEiPQHk,5529
+treadstone_cli/templates.py,sha256=Q1OMc2rAIo802Pt5eFrgIEEp20mVUwCmeCQQwyySBG0,1109
+treadstone_cli-0.2.1.dist-info/METADATA,sha256=kugHiZgcVi2qGcZShmMxvHP4Ps2Ozzx1w-C1faeEKaI,5491
+treadstone_cli-0.2.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+treadstone_cli-0.2.1.dist-info/entry_points.txt,sha256=AEweiekAwgT6jzNSIVdmYk714t6zO3xMIHv4Hhh2vII,55
+treadstone_cli-0.2.1.dist-info/RECORD,,

treadstone_cli-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

treadstone_cli-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+treadstone = treadstone_cli.main:cli