quicksilverpro 0.1.0__tar.gz

quicksilverpro-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: pip install -e .
+      - name: Smoke — version / help / public models
+        run: |
+          qsp --version
+          qsp --help
+          qsp models
+          qsp status --json > /dev/null

quicksilverpro-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,92 @@
+name: Publish to PyPI & Homebrew
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write   # Trusted Publishing (no long-lived PyPI token)
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  update-homebrew:
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - name: Wait for PyPI to propagate
+        run: sleep 30
+
+      - name: Resolve release version
+        id: version
+        # GITHUB_REF_NAME is e.g. "v0.1.0"; strip the leading "v" for PyPI.
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Fetch sdist URL and SHA256 from PyPI
+        id: pypi
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          URL=""
+          # Poll up to ~5 minutes for the new version to show on PyPI.
+          for i in $(seq 1 10); do
+            URL=$(curl -fsSL "https://pypi.org/pypi/quicksilverpro/${VERSION}/json" 2>/dev/null \
+              | python3 -c "import json,sys; d=json.load(sys.stdin); print([u['url'] for u in d['urls'] if u['packagetype']=='sdist'][0])" 2>/dev/null) && break
+            echo "Waiting for PyPI... (attempt $i)"
+            sleep 30
+          done
+          if [ -z "$URL" ]; then echo "Timed out waiting for PyPI sdist"; exit 1; fi
+
+          curl -fsSL "$URL" -o /tmp/pkg.tar.gz
+          SHA256=$(sha256sum /tmp/pkg.tar.gz | cut -d' ' -f1)
+          rm /tmp/pkg.tar.gz
+
+          echo "url=$URL" >> "$GITHUB_OUTPUT"
+          echo "sha256=$SHA256" >> "$GITHUB_OUTPUT"
+          echo "Resolved: $URL (sha256: $SHA256)"
+
+      - name: Dispatch formula update to homebrew tap
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          repository: machinefi/homebrew-qspro
+          event-type: update-formula
+          client-payload: |
+            {
+              "version": "${{ steps.version.outputs.version }}",
+              "url": "${{ steps.pypi.outputs.url }}",
+              "sha256": "${{ steps.pypi.outputs.sha256 }}"
+            }

quicksilverpro-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.env
+.DS_Store
+*.log
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/

quicksilverpro-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MachineFi Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quicksilverpro-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: quicksilverpro
+Version: 0.1.0
+Summary: CLI for QuickSilver Pro — OpenAI-compatible API for DeepSeek V3, DeepSeek R1, and Qwen 3.5 at 20% below resellers.
+Project-URL: Homepage, https://quicksilverpro.io
+Project-URL: Documentation, https://quicksilverpro.io/dashboard#quickstart
+Project-URL: Repository, https://github.com/machinefi/qspro-cli
+Project-URL: Issues, https://github.com/machinefi/qspro-cli/issues
+Project-URL: Status, https://quicksilverpro.io/status
+Author-email: "MachineFi Inc." <hello@quicksilverpro.io>
+License: MIT
+License-File: LICENSE
+Keywords: ai,api,chatgpt,cli,deepseek,inference,llm,openai,openrouter-alternative,quicksilverpro,qwen
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.25
+Requires-Dist: rich>=13
+Description-Content-Type: text/markdown
+
+# QuickSilver Pro CLI
+
+`qsp` — a command-line client for [QuickSilver Pro](https://quicksilverpro.io), an OpenAI-compatible inference API for top open-source LLMs (DeepSeek V3, DeepSeek R1, Qwen 3.5) priced 20% below OpenRouter / Together / Fireworks.
+
+Designed to be **AI-agent friendly**: every command accepts `--json` for structured output, exit codes are reliable, and the API surface is intentionally small.
+
+---
+
+## Install
+
+```bash
+pip install quicksilverpro
+```
+
+Python 3.9+. Also exports itself as `quicksilverpro` if you prefer the long name.
+
+---
+
+## Quick start
+
+```bash
+qsp init                     # opens dashboard to get a key, stores it locally
+qsp chat "Write me a haiku"  # one-shot streaming chat (deepseek-v3 by default)
+qsp balance                  # current credits
+qsp models                   # supported models with prices & context length
+qsp status                   # live per-model latency
+```
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `qsp init [--email X] [--key sk-...]` | Sign in (browser walkthrough) or paste an existing key |
+| `qsp logout` | Forget locally-stored key |
+| `qsp whoami [--json]` | Show signed-in email + balance |
+| `qsp balance [--json]` | Credit balance + lifetime spend |
+| `qsp models [--json]` | Available models + pricing + context length |
+| `qsp chat "PROMPT" [-m MODEL] [-s SYS] [--max-tokens N] [--temperature F] [--no-stream] [--json]` | One-shot completion, streams to stdout by default |
+| `qsp usage [-n 10] [--json]` | Recent calls + aggregate per-model |
+| `qsp status [--json]` | Live health of API + per-model probes |
+| `qsp keys list [--json]` | Your API keys |
+| `qsp keys create ALIAS [--monthly-limit USD] [--json]` | Create a new key with optional spend cap |
+| `qsp keys delete ALIAS [-y]` | Delete a key (confirmation prompt unless `-y`) |
+| `qsp pay {5,20,50}` | Opens Stripe checkout for a credit top-up |
+
+---
+
+## AI-agent usage
+
+Every command supports `--json` and prints OpenAI-shaped JSON to stdout with errors on stderr.
+
+```bash
+qsp models --json | jq '.[].id'
+qsp usage --json  | jq '.totals.cost'
+qsp chat "Summarize: $DOCUMENT" --json --no-stream | jq -r '.choices[0].message.content'
+```
+
+Exit codes: `0` success · `1` remote/operational error · `2` usage / auth error.
+
+---
+
+## Config
+
+Key stored at `~/.config/quicksilverpro/config.json` (chmod 600). Override with:
+
+- `QSP_API_KEY` — use this key directly, ignore stored config
+- `QSP_API_URL` — default `https://api.quicksilverpro.io/v1`
+- `QSP_AUTH_URL` — default `https://pay.quicksilverpro.io`
+- `QSP_MODEL` — default model for `qsp chat`
+- `QSP_CONFIG_DIR` — where to store config
+- `QSP_HTTP_TIMEOUT` — seconds, default 60
+
+---
+
+## Use the `openai` SDK directly
+
+You don't need this CLI to use QuickSilver Pro. The OpenAI Python / Node / Swift SDKs work with only a `base_url` change:
+
+```python
+from openai import OpenAI
+client = OpenAI(
+    base_url="https://api.quicksilverpro.io/v1",
+    api_key="sk-...",   # your QuickSilver Pro key
+)
+r = client.chat.completions.create(
+    model="deepseek-v3",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+See [quicksilverpro.io/dashboard#quickstart](https://quicksilverpro.io/dashboard#quickstart) for JS / Swift / curl.
+
+---
+
+## License
+
+MIT.
+
+QuickSilver Pro is a product of MachineFi Inc. (68 Willow Rd, Menlo Park, CA).
+
+Links: [home](https://quicksilverpro.io) · [status](https://quicksilverpro.io/status) · [terms](https://quicksilverpro.io/terms) · [privacy](https://quicksilverpro.io/privacy)

quicksilverpro-0.1.0/README.md

@@ -0,0 +1,103 @@
+# QuickSilver Pro CLI
+
+`qsp` — a command-line client for [QuickSilver Pro](https://quicksilverpro.io), an OpenAI-compatible inference API for top open-source LLMs (DeepSeek V3, DeepSeek R1, Qwen 3.5) priced 20% below OpenRouter / Together / Fireworks.
+
+Designed to be **AI-agent friendly**: every command accepts `--json` for structured output, exit codes are reliable, and the API surface is intentionally small.
+
+---
+
+## Install
+
+```bash
+pip install quicksilverpro
+```
+
+Python 3.9+. Also exports itself as `quicksilverpro` if you prefer the long name.
+
+---
+
+## Quick start
+
+```bash
+qsp init                     # opens dashboard to get a key, stores it locally
+qsp chat "Write me a haiku"  # one-shot streaming chat (deepseek-v3 by default)
+qsp balance                  # current credits
+qsp models                   # supported models with prices & context length
+qsp status                   # live per-model latency
+```
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `qsp init [--email X] [--key sk-...]` | Sign in (browser walkthrough) or paste an existing key |
+| `qsp logout` | Forget locally-stored key |
+| `qsp whoami [--json]` | Show signed-in email + balance |
+| `qsp balance [--json]` | Credit balance + lifetime spend |
+| `qsp models [--json]` | Available models + pricing + context length |
+| `qsp chat "PROMPT" [-m MODEL] [-s SYS] [--max-tokens N] [--temperature F] [--no-stream] [--json]` | One-shot completion, streams to stdout by default |
+| `qsp usage [-n 10] [--json]` | Recent calls + aggregate per-model |
+| `qsp status [--json]` | Live health of API + per-model probes |
+| `qsp keys list [--json]` | Your API keys |
+| `qsp keys create ALIAS [--monthly-limit USD] [--json]` | Create a new key with optional spend cap |
+| `qsp keys delete ALIAS [-y]` | Delete a key (confirmation prompt unless `-y`) |
+| `qsp pay {5,20,50}` | Opens Stripe checkout for a credit top-up |
+
+---
+
+## AI-agent usage
+
+Every command supports `--json` and prints OpenAI-shaped JSON to stdout with errors on stderr.
+
+```bash
+qsp models --json | jq '.[].id'
+qsp usage --json  | jq '.totals.cost'
+qsp chat "Summarize: $DOCUMENT" --json --no-stream | jq -r '.choices[0].message.content'
+```
+
+Exit codes: `0` success · `1` remote/operational error · `2` usage / auth error.
+
+---
+
+## Config
+
+Key stored at `~/.config/quicksilverpro/config.json` (chmod 600). Override with:
+
+- `QSP_API_KEY` — use this key directly, ignore stored config
+- `QSP_API_URL` — default `https://api.quicksilverpro.io/v1`
+- `QSP_AUTH_URL` — default `https://pay.quicksilverpro.io`
+- `QSP_MODEL` — default model for `qsp chat`
+- `QSP_CONFIG_DIR` — where to store config
+- `QSP_HTTP_TIMEOUT` — seconds, default 60
+
+---
+
+## Use the `openai` SDK directly
+
+You don't need this CLI to use QuickSilver Pro. The OpenAI Python / Node / Swift SDKs work with only a `base_url` change:
+
+```python
+from openai import OpenAI
+client = OpenAI(
+    base_url="https://api.quicksilverpro.io/v1",
+    api_key="sk-...",   # your QuickSilver Pro key
+)
+r = client.chat.completions.create(
+    model="deepseek-v3",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+See [quicksilverpro.io/dashboard#quickstart](https://quicksilverpro.io/dashboard#quickstart) for JS / Swift / curl.
+
+---
+
+## License
+
+MIT.
+
+QuickSilver Pro is a product of MachineFi Inc. (68 Willow Rd, Menlo Park, CA).
+
+Links: [home](https://quicksilverpro.io) · [status](https://quicksilverpro.io/status) · [terms](https://quicksilverpro.io/terms) · [privacy](https://quicksilverpro.io/privacy)

quicksilverpro-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "quicksilverpro"
+version = "0.1.0"
+description = "CLI for QuickSilver Pro — OpenAI-compatible API for DeepSeek V3, DeepSeek R1, and Qwen 3.5 at 20% below resellers."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "MachineFi Inc.", email = "hello@quicksilverpro.io" }]
+keywords = [
+  "openai", "deepseek", "qwen", "llm", "inference", "api",
+  "chatgpt", "ai", "cli", "openrouter-alternative", "quicksilverpro",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "click>=8.1",
+  "httpx>=0.25",
+  "rich>=13",
+]
+
+[project.urls]
+Homepage     = "https://quicksilverpro.io"
+Documentation = "https://quicksilverpro.io/dashboard#quickstart"
+Repository   = "https://github.com/machinefi/qspro-cli"
+Issues       = "https://github.com/machinefi/qspro-cli/issues"
+Status       = "https://quicksilverpro.io/status"
+
+[project.scripts]
+qsp = "quicksilverpro.cli:main"
+quicksilverpro = "quicksilverpro.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/quicksilverpro"]

quicksilverpro-0.1.0/src/quicksilverpro/__init__.py

@@ -0,0 +1,6 @@
+"""QuickSilver Pro command-line interface.
+
+See https://quicksilverpro.io for docs. `qsp --help` for quick reference.
+"""
+
+__version__ = "0.1.0"

quicksilverpro-0.1.0/src/quicksilverpro/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m quicksilverpro ...` as an alias for the `qsp` entrypoint."""
+from .cli import main
+
+if __name__ == "__main__":
+    main()

quicksilverpro-0.1.0/src/quicksilverpro/cli.py

@@ -0,0 +1,599 @@
+"""QuickSilver Pro CLI — single-file implementation.
+
+Design goals:
+  1. Drop-in OpenAI-compatible thin wrapper: `qsp chat "..."` works immediately.
+  2. AI-agent friendly: every command accepts `--json` and emits structured
+     output on stdout with errors on stderr and non-zero exit codes on failure.
+  3. No config surprises: API key lives in `~/.config/quicksilverpro/config.json`
+     (or `$QSP_CONFIG_DIR`); the `QSP_API_KEY` env var overrides.
+
+The CLI talks to two endpoints:
+  - https://api.quicksilverpro.io/v1   — OpenAI-shaped inference
+  - https://pay.quicksilverpro.io/v1   — account + usage + keys management
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+import webbrowser
+from pathlib import Path
+
+import click
+import httpx
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__
+
+# ────────────────────────── constants ──────────────────────────
+
+DEFAULT_API_URL  = os.environ.get("QSP_API_URL",  "https://api.quicksilverpro.io/v1")
+DEFAULT_AUTH_URL = os.environ.get("QSP_AUTH_URL", "https://pay.quicksilverpro.io")
+DEFAULT_APP_URL  = os.environ.get("QSP_APP_URL",  "https://quicksilverpro.io")
+DEFAULT_MODEL    = os.environ.get("QSP_MODEL",    "deepseek-v3")
+HTTP_TIMEOUT     = float(os.environ.get("QSP_HTTP_TIMEOUT", "60"))
+
+CONFIG_DIR = Path(os.environ.get("QSP_CONFIG_DIR",
+                                 Path.home() / ".config" / "quicksilverpro"))
+CONFIG_PATH = CONFIG_DIR / "config.json"
+
+# stderr for humans, stdout reserved for parseable data when `--json` is used.
+_err = Console(stderr=True)
+_out = Console()
+
+
+# ────────────────────────── config + auth ──────────────────────────
+
+def _load_config() -> dict:
+    if not CONFIG_PATH.exists():
+        return {}
+    try:
+        return json.loads(CONFIG_PATH.read_text())
+    except Exception:
+        return {}
+
+
+def _save_config(cfg: dict) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_text(json.dumps(cfg, indent=2))
+    try:
+        os.chmod(CONFIG_PATH, 0o600)  # key is sensitive — best-effort on POSIX.
+    except Exception:
+        pass
+
+
+def _resolve_api_key() -> str | None:
+    """QSP_API_KEY env var wins; else fall back to ~/.config store."""
+    env = os.environ.get("QSP_API_KEY") or os.environ.get("OPENAI_API_KEY_QSP")
+    if env:
+        return env.strip()
+    return (_load_config().get("api_key") or "").strip() or None
+
+
+def _require_key() -> str:
+    k = _resolve_api_key()
+    if not k:
+        _err.print(
+            "[red]Not signed in.[/red] Run [bold]qsp init[/bold] to get started, "
+            "or set [bold]QSP_API_KEY[/bold] in your environment."
+        )
+        sys.exit(2)
+    return k
+
+
+# ────────────────────────── http helpers ──────────────────────────
+
+def _auth_client(key: str | None = None) -> httpx.Client:
+    headers = {"User-Agent": f"quicksilverpro-cli/{__version__}"}
+    if key:
+        headers["Authorization"] = f"Bearer {key}"
+    return httpx.Client(
+        base_url=DEFAULT_AUTH_URL,
+        timeout=HTTP_TIMEOUT,
+        headers=headers,
+        follow_redirects=False,
+    )
+
+
+def _api_client(key: str) -> httpx.Client:
+    return httpx.Client(
+        base_url=DEFAULT_API_URL,
+        timeout=HTTP_TIMEOUT,
+        headers={
+            "Authorization": f"Bearer {key}",
+            "User-Agent": f"quicksilverpro-cli/{__version__}",
+            "Content-Type": "application/json",
+        },
+        follow_redirects=False,
+    )
+
+
+def _extract_error(resp: httpx.Response) -> str:
+    try:
+        d = resp.json()
+        if isinstance(d, dict):
+            err = d.get("error")
+            if isinstance(err, dict):
+                return err.get("message") or str(err)
+            if isinstance(d.get("detail"), str):
+                return d["detail"]
+            return json.dumps(d)
+        return resp.text
+    except Exception:
+        return resp.text or f"HTTP {resp.status_code}"
+
+
+def _emit(obj, *, as_json: bool, table_fn=None) -> None:
+    """JSON goes to stdout; pretty tables go through Rich to stdout."""
+    if as_json:
+        click.echo(json.dumps(obj, indent=2, default=str))
+        return
+    if table_fn:
+        table_fn(obj)
+    else:
+        click.echo(json.dumps(obj, indent=2, default=str))
+
+
+# ────────────────────────── root command group ──────────────────────────
+
+@click.group(
+    help=(
+        "QuickSilver Pro — OpenAI-compatible API for top open-source LLMs.\n\n"
+        "Docs: https://quicksilverpro.io  ·  Status: https://quicksilverpro.io/status"
+    ),
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.version_option(__version__, prog_name="qsp")
+def main() -> None:
+    pass
+
+
+# ────────────────────────── qsp init ──────────────────────────
+
+@main.command(help="Sign in: opens the dashboard in a browser, you paste the API key back.")
+@click.option("--key", "apikey", default=None, help="Paste an existing API key instead of opening the browser.")
+@click.option("--email", default=None, help="Email for a new account (sends verification link).")
+def init(apikey: str | None, email: str | None) -> None:
+    # Three paths: explicit --key, new-account via --email, or default browser walk-through.
+    if apikey:
+        _save_key(apikey)
+        return
+
+    if email:
+        with _auth_client() as c:
+            r = c.post("/v1/register", json={"email": email})
+        if r.status_code >= 400:
+            _err.print(f"[red]Register failed:[/red] {_extract_error(r)}")
+            sys.exit(1)
+        data = r.json()
+        if data.get("verification_required"):
+            _out.print(f"✓ Verification email sent to [bold]{email}[/bold]. Click the magic link, "
+                       f"copy the key from the dashboard, then run [bold]qsp init --key sk-...[/bold]")
+            return
+        # Legacy path (email not configured) — returns key immediately.
+        if k := data.get("key"):
+            _save_key(k)
+            return
+        _err.print("[red]Unexpected register response shape.[/red]")
+        sys.exit(1)
+
+    # Default walkthrough: open the dashboard and guide copy-paste.
+    _out.print("Opening [bold]quicksilverpro.io/dashboard[/bold] — sign up or sign in, copy your API key, then paste below.")
+    try:
+        webbrowser.open(f"{DEFAULT_APP_URL}/dashboard")
+    except Exception:
+        pass
+    pasted = click.prompt("Paste API key", hide_input=True, default="", show_default=False).strip()
+    if not pasted:
+        _err.print("[red]No key entered — aborted.[/red]")
+        sys.exit(1)
+    _save_key(pasted)
+
+
+def _save_key(apikey: str) -> None:
+    if not apikey.startswith("sk-"):
+        _err.print("[red]That doesn't look like an API key (must start with sk-).[/red]")
+        sys.exit(1)
+    # Verify by calling /v1/me — catches typos + dead keys up-front.
+    with _auth_client(apikey) as c:
+        r = c.get("/v1/me")
+    if r.status_code >= 400:
+        _err.print(f"[red]Key rejected by server:[/red] {_extract_error(r)}")
+        sys.exit(1)
+    info = r.json()
+    cfg = _load_config()
+    cfg["api_key"] = apikey
+    cfg["email"] = info.get("email") or cfg.get("email", "")
+    _save_config(cfg)
+    _out.print(f"✓ Signed in as [bold]{info.get('email') or 'unknown'}[/bold]. Key stored at {CONFIG_PATH}.")
+
+
+# ────────────────────────── qsp logout / whoami ──────────────────────────
+
+@main.command(help="Forget the locally-stored API key.")
+def logout() -> None:
+    if CONFIG_PATH.exists():
+        CONFIG_PATH.unlink()
+    _out.print("✓ Signed out.")
+
+
+@main.command(help="Show the email the CLI is signed in as.")
+@click.option("--json", "as_json", is_flag=True)
+def whoami(as_json: bool) -> None:
+    key = _require_key()
+    with _auth_client(key) as c:
+        r = c.get("/v1/me")
+    if r.status_code >= 400:
+        _err.print(f"[red]{_extract_error(r)}[/red]")
+        sys.exit(1)
+    info = r.json()
+    info["api_base"] = DEFAULT_API_URL
+    _emit(info, as_json=as_json, table_fn=_print_whoami)
+
+
+def _print_whoami(info: dict) -> None:
+    _out.print(f"Email:      [bold]{info.get('email','—')}[/bold]")
+    _out.print(f"Balance:    [bold]${max(0, (info.get('max_budget') or 0) - (info.get('spend') or 0)):.4f}[/bold]")
+    _out.print(f"Total spent: ${info.get('spend') or 0:.4f}")
+    _out.print(f"API base:   {info.get('api_base')}")
+
+
+# ────────────────────────── qsp balance ──────────────────────────
+
+@main.command(help="Show current account balance and spend.")
+@click.option("--json", "as_json", is_flag=True)
+def balance(as_json: bool) -> None:
+    key = _require_key()
+    with _auth_client(key) as c:
+        r = c.get("/v1/me")
+    if r.status_code >= 400:
+        _err.print(f"[red]{_extract_error(r)}[/red]")
+        sys.exit(1)
+    info = r.json()
+    bal = max(0, (info.get("max_budget") or 0) - (info.get("spend") or 0))
+    payload = {
+        "balance":    round(bal, 6),
+        "loaded":     info.get("max_budget") or 0,
+        "spent":      info.get("spend") or 0,
+        "currency":   "USD",
+    }
+    _emit(payload, as_json=as_json, table_fn=lambda p:
+          _out.print(f"Balance: [bold]${p['balance']:.4f}[/bold] of ${p['loaded']:.2f} loaded · spent ${p['spent']:.4f}"))
+
+
+# ────────────────────────── qsp models ──────────────────────────
+
+# Hardcoded so `qsp models` works before the user has signed in. Keep in sync
+# with the backend; tests in CI should catch drift.
+_MODELS_FALLBACK: list[dict] = [
+    {"id": "deepseek-v3", "object": "model", "owned_by": "quicksilverpro",
+     "context_length": 131072,
+     "pricing": {"prompt": "0.0000002400", "completion": "0.0000007000"},
+     "best_for": "chat, coding, structured output"},
+    {"id": "deepseek-r1", "object": "model", "owned_by": "quicksilverpro",
+     "context_length": 131072,
+     "pricing": {"prompt": "0.0000004000", "completion": "0.0000017000"},
+     "best_for": "math, multi-step reasoning, logic"},
+    {"id": "qwen3.5-35b", "object": "model", "owned_by": "quicksilverpro",
+     "context_length": 262144,
+     "pricing": {"prompt": "0.0000001300", "completion": "0.0000010000"},
+     "best_for": "long-context RAG, summarization (thinking model)"},
+]
+
+
+@main.command(help="List available models.")
+@click.option("--json", "as_json", is_flag=True)
+def models(as_json: bool) -> None:
+    # Try the live endpoint for freshness; fall back to our shipped list if
+    # the user isn't signed in, so `qsp models` is useful before `qsp init`.
+    key = _resolve_api_key()
+    data: list[dict] = []
+    if key:
+        try:
+            with httpx.Client(
+                base_url=DEFAULT_API_URL,
+                timeout=HTTP_TIMEOUT,
+                headers={"Authorization": f"Bearer {key}"},
+            ) as c:
+                r = c.get("/models")
+            if r.status_code < 400:
+                data = r.json().get("data", [])
+        except httpx.HTTPError:
+            data = []
+    if not data:
+        data = _MODELS_FALLBACK
+    _emit(data, as_json=as_json, table_fn=_print_models)
+
+
+def _print_models(rows: list[dict]) -> None:
+    t = Table(show_lines=False)
+    t.add_column("id", style="bold")
+    t.add_column("context", justify="right")
+    t.add_column("prompt $/M", justify="right")
+    t.add_column("completion $/M", justify="right")
+    for m in rows:
+        p = m.get("pricing") or {}
+        ctx = m.get("context_length")
+        t.add_row(
+            m.get("id", ""),
+            f"{ctx:,}" if ctx else "—",
+            f"{float(p.get('prompt', 0)) * 1_000_000:.2f}" if p else "—",
+            f"{float(p.get('completion', 0)) * 1_000_000:.2f}" if p else "—",
+        )
+    _out.print(t)
+
+
+# ────────────────────────── qsp chat ──────────────────────────
+
+@main.command(help="One-shot chat completion. Echoes to stdout.")
+@click.argument("prompt")
+@click.option("-m", "--model", default=DEFAULT_MODEL, show_default=True)
+@click.option("-s", "--system", default=None, help="Optional system prompt.")
+@click.option("--max-tokens", type=int, default=None)
+@click.option("--temperature", type=float, default=None)
+@click.option("--stream/--no-stream", default=True, show_default=True)
+@click.option("--json", "as_json", is_flag=True, help="Emit raw JSON response (implies --no-stream).")
+def chat(prompt: str, model: str, system: str | None, max_tokens: int | None,
+         temperature: float | None, stream: bool, as_json: bool) -> None:
+    key = _require_key()
+    messages: list[dict] = []
+    if system:
+        messages.append({"role": "system", "content": system})
+    messages.append({"role": "user", "content": prompt})
+
+    body = {"model": model, "messages": messages}
+    if max_tokens is not None:   body["max_tokens"]   = max_tokens
+    if temperature is not None:  body["temperature"] = temperature
+
+    # --json means we want the full structured response, so force non-streaming.
+    if as_json:
+        stream = False
+
+    if stream:
+        body["stream"] = True
+        body["stream_options"] = {"include_usage": True}
+        _chat_stream(key, body)
+    else:
+        _chat_sync(key, body, as_json=as_json)
+
+
+def _chat_sync(key: str, body: dict, as_json: bool) -> None:
+    with _api_client(key) as c:
+        r = c.post("/chat/completions", json=body)
+    if r.status_code >= 400:
+        _err.print(f"[red]{_extract_error(r)}[/red]")
+        sys.exit(1)
+    data = r.json()
+    if as_json:
+        click.echo(json.dumps(data, indent=2))
+        return
+    msg = ((data.get("choices") or [{}])[0].get("message") or {}).get("content") or ""
+    click.echo(msg)
+    usage = data.get("usage") or {}
+    cost = usage.get("cost")
+    if cost is not None:
+        _err.print(
+            f"[dim]{usage.get('prompt_tokens',0)} in + "
+            f"{usage.get('completion_tokens',0)} out · "
+            f"${cost:.6f}[/dim]"
+        )
+
+
+def _chat_stream(key: str, body: dict) -> None:
+    last_usage = {}
+    try:
+        with _api_client(key).stream("POST", "/chat/completions", json=body) as r:
+            if r.status_code >= 400:
+                _err.print(f"[red]{_extract_error(r)}[/red]")
+                sys.exit(1)
+            for line in r.iter_lines():
+                if not line or not line.startswith("data:"):
+                    continue
+                payload = line[5:].strip()
+                if not payload or payload == "[DONE]":
+                    continue
+                try:
+                    ev = json.loads(payload)
+                except Exception:
+                    continue
+                for ch in ev.get("choices") or []:
+                    delta = (ch.get("delta") or {})
+                    if delta.get("content"):
+                        sys.stdout.write(delta["content"])
+                        sys.stdout.flush()
+                if ev.get("usage"):
+                    last_usage = ev["usage"]
+    except httpx.HTTPError as e:
+        _err.print(f"\n[red]Network error:[/red] {e}")
+        sys.exit(1)
+    sys.stdout.write("\n")
+    if last_usage.get("cost") is not None:
+        _err.print(
+            f"[dim]{last_usage.get('prompt_tokens',0)} in + "
+            f"{last_usage.get('completion_tokens',0)} out · "
+            f"${last_usage['cost']:.6f}[/dim]"
+        )
+
+
+# ────────────────────────── qsp keys ──────────────────────────
+
+@main.group(help="Manage API keys.")
+def keys() -> None: pass
+
+
+@keys.command("list", help="List all of your API keys.")
+@click.option("--json", "as_json", is_flag=True)
+def keys_list(as_json: bool) -> None:
+    key = _require_key()
+    with _auth_client(key) as c:
+        r = c.get("/v1/keys")
+    if r.status_code >= 400:
+        _err.print(f"[red]{_extract_error(r)}[/red]")
+        sys.exit(1)
+    rows = r.json().get("keys", [])
+    _emit(rows, as_json=as_json, table_fn=_print_keys)
+
+
+def _print_keys(rows: list[dict]) -> None:
+    t = Table(show_lines=False)
+    t.add_column("alias", style="bold")
+    t.add_column("key")
+    t.add_column("monthly limit", justify="right")
+    t.add_column("spend", justify="right")
+    t.add_column("current?")
+    for k in rows:
+        lim = k.get("monthly_limit")
+        t.add_row(
+            k.get("alias", "—"),
+            k.get("key_name") or "",
+            f"${lim:.4f}/30d" if lim is not None else "—",
+            f"${k.get('spend') or 0:.4f}",
+            "✓" if k.get("is_current") else "",
+        )
+    _out.print(t)
+
+
+@keys.command("create", help="Create a new API key.")
+@click.argument("alias")
+@click.option("--monthly-limit", type=float, default=None, help="Max USD this key can spend per 30 days.")
+@click.option("--json", "as_json", is_flag=True)
+def keys_create(alias: str, monthly_limit: float | None, as_json: bool) -> None:
+    key = _require_key()
+    body = {"alias": alias}
+    if monthly_limit is not None:
+        body["monthly_limit"] = monthly_limit
+    with _auth_client(key) as c:
+        r = c.post("/v1/keys", json=body)
+    if r.status_code >= 400:
+        _err.print(f"[red]{_extract_error(r)}[/red]")
+        sys.exit(1)
+    data = r.json()
+    if as_json:
+        click.echo(json.dumps(data, indent=2))
+        return
+    _out.print(f"✓ Created key [bold]{data.get('alias')}[/bold]")
+    _out.print(f"  {data.get('key')}")
+    _out.print("[yellow]Copy it now — it won't be shown again.[/yellow]")
+
+
+@keys.command("delete", help="Delete an API key by alias.")
+@click.argument("alias")
+@click.option("-y", "--yes", is_flag=True, help="Skip the confirmation prompt.")
+def keys_delete(alias: str, yes: bool) -> None:
+    key = _require_key()
+    with _auth_client(key) as c:
+        r = c.get("/v1/keys")
+    if r.status_code >= 400:
+        _err.print(f"[red]{_extract_error(r)}[/red]")
+        sys.exit(1)
+    matches = [k for k in r.json().get("keys", []) if k.get("alias") == alias]
+    if not matches:
+        _err.print(f"[red]No key with alias '{alias}'.[/red]")
+        sys.exit(1)
+    target = matches[0]
+    if not yes:
+        click.confirm(f"Delete key '{alias}' ({target.get('key_name')})?", abort=True)
+    with _auth_client(key) as c:
+        r = c.post("/v1/keys/delete", json={"token": target["token"]})
+    if r.status_code >= 400:
+        _err.print(f"[red]{_extract_error(r)}[/red]")
+        sys.exit(1)
+    _out.print(f"✓ Deleted [bold]{alias}[/bold].")
+
+
+# ────────────────────────── qsp usage ──────────────────────────
+
+@main.command(help="Recent API calls with cost.")
+@click.option("-n", "--limit", type=int, default=10, show_default=True)
+@click.option("--json", "as_json", is_flag=True)
+def usage(limit: int, as_json: bool) -> None:
+    key = _require_key()
+    with _auth_client(key) as c:
+        r = c.get("/v1/usage")
+    if r.status_code >= 400:
+        _err.print(f"[red]{_extract_error(r)}[/red]")
+        sys.exit(1)
+    data = r.json()
+    data["recent"] = (data.get("recent") or [])[:limit]
+    _emit(data, as_json=as_json, table_fn=_print_usage)
+
+
+def _print_usage(data: dict) -> None:
+    totals = data.get("totals") or {}
+    _out.print(
+        f"Total: [bold]{totals.get('requests',0)}[/bold] requests · "
+        f"{totals.get('tokens',0):,} tokens · "
+        f"${totals.get('cost',0):.4f}"
+    )
+    by_model = data.get("by_model") or []
+    if by_model:
+        t = Table(title="By model")
+        t.add_column("model", style="bold"); t.add_column("requests", justify="right")
+        t.add_column("tokens", justify="right"); t.add_column("cost", justify="right")
+        for m in by_model:
+            t.add_row(m["model"], str(m["requests"]), f"{m['tokens']:,}", f"${m['cost']:.4f}")
+        _out.print(t)
+    recent = data.get("recent") or []
+    if recent:
+        t = Table(title="Recent requests")
+        t.add_column("model", style="bold"); t.add_column("tokens", justify="right")
+        t.add_column("latency", justify="right"); t.add_column("cost", justify="right"); t.add_column("at")
+        for r in recent:
+            t.add_row(r["model"], str(r.get("tokens", 0)),
+                      f"{(r.get('duration_ms') or 0)/1000:.2f}s",
+                      f"${r.get('cost',0):.6f}", r.get("at", "")[:19])
+        _out.print(t)
+
+
+# ────────────────────────── qsp status ──────────────────────────
+
+@main.command(help="Check service status (routes + per-model latency).")
+@click.option("--json", "as_json", is_flag=True)
+def status(as_json: bool) -> None:
+    with httpx.Client(base_url=DEFAULT_AUTH_URL, timeout=HTTP_TIMEOUT) as c:
+        r = c.get("/v1/status")
+    if r.status_code >= 400:
+        _err.print(f"[red]{_extract_error(r)}[/red]")
+        sys.exit(1)
+    data = r.json()
+    _emit(data, as_json=as_json, table_fn=_print_status)
+
+
+def _print_status(data: dict) -> None:
+    overall = (data.get("overall") or "unknown").upper()
+    color = {"OPERATIONAL": "green", "DEGRADED": "yellow",
+             "PARTIAL_OUTAGE": "yellow", "MAJOR_OUTAGE": "red"}.get(overall, "white")
+    _out.print(f"Overall: [bold {color}]{overall}[/bold {color}]")
+    t = Table(show_lines=False)
+    t.add_column("model", style="bold"); t.add_column("status")
+    t.add_column("latency (ms)", justify="right")
+    for m in data.get("models") or []:
+        t.add_row(m["model"], m["status"], str(m.get("latency_ms") or "—"))
+    _out.print(t)
+
+
+# ────────────────────────── qsp pay ──────────────────────────
+
+@main.command(help="Open the Stripe checkout for a credit pack ($5 / $20 / $50).")
+@click.argument("amount", type=click.Choice(["5", "20", "50"]))
+def pay(amount: str) -> None:
+    urls = {
+        "5":  "https://buy.stripe.com/6oU9AT5eC2aGexN4t4gjC03",
+        "20": "https://buy.stripe.com/6oU5kD0YmbLg9dt9NogjC04",
+        "50": "https://buy.stripe.com/7sYbJ1ePc7v0ahxcZAgjC05",
+    }
+    url = urls[amount]
+    _out.print(f"Opening checkout for [bold]${amount}[/bold]: {url}")
+    try:
+        webbrowser.open(url)
+    except Exception:
+        pass
+
+
+# ────────────────────────── entrypoint ──────────────────────────
+
+if __name__ == "__main__":
+    main()