race-ai 0.1.0__tar.gz

race_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Race Engineering
+
+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.

race_ai-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: race-ai
+Version: 0.1.0
+Summary: Race Engineering GPU cloud CLI
+License-Expression: MIT
+Project-URL: Homepage, https://raceengineering.ai
+Project-URL: Documentation, https://raceengineering.ai/docs/cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: LICENSE:Zone.Identifier
+Requires-Dist: typer<1.0,>=0.9
+Requires-Dist: requests<3.0,>=2.31
+Requires-Dist: keyring<26.0,>=24.0
+Requires-Dist: rich<15.0,>=13.0
+Dynamic: license-file
+
+# race-cli
+
+Command-line interface for the Race Engineering GPU cloud platform.
+
+## Install
+
+```bash
+pip install race-cli
+```
+
+## Quick start
+
+```bash
+# Generate an API key first, via the Race Engineering web dashboard
+# (Account Settings -> API Keys -> Create Key)
+
+race login --key rk_xxxxxxxxxxxxxxxxxxxxxxxx
+race deploy --gpu <slice_id> --template <template_id>
+race status <pod_id>
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `race login --key <key>` | Store an API key locally (OS keychain — never a plaintext file) |
+| `race logout` | Remove the locally stored key |
+| `race deploy --gpu <slice_id> --template <template_id>` | Deploy a new GPU pod |
+| `race list` | List your pods |
+| `race status <pod_id>` | Check a pod's deploy status |
+| `race pause <pod_id>` | Pause a running pod |
+| `race resume <pod_id>` | Resume a paused pod |
+| `race terminate <pod_id> [--yes]` | Terminate a pod (asks for confirmation unless `--yes`) |
+
+Run `race --help` or `race <command> --help` for full option details at any time.
+
+## Configuration
+
+By default the CLI talks to the production API. To point it elsewhere (e.g. a
+self-hosted or staging instance):
+
+```bash
+race login --key <key> --base-url https://your-instance.example.com
+```
+
+The base URL is remembered for future commands — you don't need to pass it every time.
+
+## Authentication & security
+
+- API keys are generated through the web dashboard, not this CLI — `race login` only
+  *stores* a key you already have.
+- Keys are stored using your operating system's credential store (macOS Keychain,
+  Windows Credential Manager, Linux Secret Service) via the `keyring` package — never
+  written to a plaintext file on disk.
+- `race login` validates the key against the API before storing it, so a mistyped or
+  invalid key is never silently saved.
+
+## Retries and idempotency
+
+`race deploy` automatically retries once on a network-layer failure (timeout, dropped
+connection) using the same idempotency key for every retry of that attempt — this
+guarantees a retried deploy can never accidentally create a second pod. A definitive
+error response from the server (e.g. insufficient balance, invalid template) is not
+retried.
+
+## Requirements
+
+- Python 3.9+
+- A Race Engineering account and API key
+
+## License
+
+MIT — see [LICENSE](LICENSE).

race_ai-0.1.0/README.md

@@ -0,0 +1,73 @@
+# race-cli
+
+Command-line interface for the Race Engineering GPU cloud platform.
+
+## Install
+
+```bash
+pip install race-cli
+```
+
+## Quick start
+
+```bash
+# Generate an API key first, via the Race Engineering web dashboard
+# (Account Settings -> API Keys -> Create Key)
+
+race login --key rk_xxxxxxxxxxxxxxxxxxxxxxxx
+race deploy --gpu <slice_id> --template <template_id>
+race status <pod_id>
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `race login --key <key>` | Store an API key locally (OS keychain — never a plaintext file) |
+| `race logout` | Remove the locally stored key |
+| `race deploy --gpu <slice_id> --template <template_id>` | Deploy a new GPU pod |
+| `race list` | List your pods |
+| `race status <pod_id>` | Check a pod's deploy status |
+| `race pause <pod_id>` | Pause a running pod |
+| `race resume <pod_id>` | Resume a paused pod |
+| `race terminate <pod_id> [--yes]` | Terminate a pod (asks for confirmation unless `--yes`) |
+
+Run `race --help` or `race <command> --help` for full option details at any time.
+
+## Configuration
+
+By default the CLI talks to the production API. To point it elsewhere (e.g. a
+self-hosted or staging instance):
+
+```bash
+race login --key <key> --base-url https://your-instance.example.com
+```
+
+The base URL is remembered for future commands — you don't need to pass it every time.
+
+## Authentication & security
+
+- API keys are generated through the web dashboard, not this CLI — `race login` only
+  *stores* a key you already have.
+- Keys are stored using your operating system's credential store (macOS Keychain,
+  Windows Credential Manager, Linux Secret Service) via the `keyring` package — never
+  written to a plaintext file on disk.
+- `race login` validates the key against the API before storing it, so a mistyped or
+  invalid key is never silently saved.
+
+## Retries and idempotency
+
+`race deploy` automatically retries once on a network-layer failure (timeout, dropped
+connection) using the same idempotency key for every retry of that attempt — this
+guarantees a retried deploy can never accidentally create a second pod. A definitive
+error response from the server (e.g. insufficient balance, invalid template) is not
+retried.
+
+## Requirements
+
+- Python 3.9+
+- A Race Engineering account and API key
+
+## License
+
+MIT — see [LICENSE](LICENSE).

race_ai-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "race-ai"
+version = "0.1.0"
+description = "Race Engineering GPU cloud CLI"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = [
+    "typer>=0.9,<1.0",
+    "requests>=2.31,<3.0",
+    "keyring>=24.0,<26.0",
+    "rich>=13.0,<15.0",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://raceengineering.ai"
+Documentation = "https://raceengineering.ai/docs/cli"
+
+[project.scripts]
+race = "race_cli.cli:main"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"

race_ai-0.1.0/race_ai.egg-info/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: race-ai
+Version: 0.1.0
+Summary: Race Engineering GPU cloud CLI
+License-Expression: MIT
+Project-URL: Homepage, https://raceengineering.ai
+Project-URL: Documentation, https://raceengineering.ai/docs/cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: LICENSE:Zone.Identifier
+Requires-Dist: typer<1.0,>=0.9
+Requires-Dist: requests<3.0,>=2.31
+Requires-Dist: keyring<26.0,>=24.0
+Requires-Dist: rich<15.0,>=13.0
+Dynamic: license-file
+
+# race-cli
+
+Command-line interface for the Race Engineering GPU cloud platform.
+
+## Install
+
+```bash
+pip install race-cli
+```
+
+## Quick start
+
+```bash
+# Generate an API key first, via the Race Engineering web dashboard
+# (Account Settings -> API Keys -> Create Key)
+
+race login --key rk_xxxxxxxxxxxxxxxxxxxxxxxx
+race deploy --gpu <slice_id> --template <template_id>
+race status <pod_id>
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `race login --key <key>` | Store an API key locally (OS keychain — never a plaintext file) |
+| `race logout` | Remove the locally stored key |
+| `race deploy --gpu <slice_id> --template <template_id>` | Deploy a new GPU pod |
+| `race list` | List your pods |
+| `race status <pod_id>` | Check a pod's deploy status |
+| `race pause <pod_id>` | Pause a running pod |
+| `race resume <pod_id>` | Resume a paused pod |
+| `race terminate <pod_id> [--yes]` | Terminate a pod (asks for confirmation unless `--yes`) |
+
+Run `race --help` or `race <command> --help` for full option details at any time.
+
+## Configuration
+
+By default the CLI talks to the production API. To point it elsewhere (e.g. a
+self-hosted or staging instance):
+
+```bash
+race login --key <key> --base-url https://your-instance.example.com
+```
+
+The base URL is remembered for future commands — you don't need to pass it every time.
+
+## Authentication & security
+
+- API keys are generated through the web dashboard, not this CLI — `race login` only
+  *stores* a key you already have.
+- Keys are stored using your operating system's credential store (macOS Keychain,
+  Windows Credential Manager, Linux Secret Service) via the `keyring` package — never
+  written to a plaintext file on disk.
+- `race login` validates the key against the API before storing it, so a mistyped or
+  invalid key is never silently saved.
+
+## Retries and idempotency
+
+`race deploy` automatically retries once on a network-layer failure (timeout, dropped
+connection) using the same idempotency key for every retry of that attempt — this
+guarantees a retried deploy can never accidentally create a second pod. A definitive
+error response from the server (e.g. insufficient balance, invalid template) is not
+retried.
+
+## Requirements
+
+- Python 3.9+
+- A Race Engineering account and API key
+
+## License
+
+MIT — see [LICENSE](LICENSE).

race_ai-0.1.0/race_ai.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+LICENSE:Zone.Identifier
+README.md
+pyproject.toml
+race_ai.egg-info/PKG-INFO
+race_ai.egg-info/SOURCES.txt
+race_ai.egg-info/dependency_links.txt
+race_ai.egg-info/entry_points.txt
+race_ai.egg-info/requires.txt
+race_ai.egg-info/top_level.txt
+race_cli/__init__.py
+race_cli/__main__.py
+race_cli/api_client.py
+race_cli/cli.py
+race_cli/config.py

race_ai-0.1.0/race_ai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

race_ai-0.1.0/race_ai.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+race = race_cli.cli:main

race_ai-0.1.0/race_ai.egg-info/requires.txt

@@ -0,0 +1,4 @@
+typer<1.0,>=0.9
+requests<3.0,>=2.31
+keyring<26.0,>=24.0
+rich<15.0,>=13.0

race_ai-0.1.0/race_ai.egg-info/top_level.txt

@@ -0,0 +1 @@
+race_cli

race_ai-0.1.0/race_cli/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

race_ai-0.1.0/race_cli/api_client.py

@@ -0,0 +1,180 @@
+"""
+Thin wrapper over the race API. Every CLI command goes through here —
+never makes a raw `requests` call inline in a command function. This is
+the same services-vs-views separation from the backend, applied to the
+CLI: command functions (cli.py) handle argument parsing and terminal
+output; this module handles "how do I actually talk to the API."
+"""
+
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+import requests
+
+from . import config
+
+
+class RaceAPIError(Exception):
+    """
+    Raised for any non-2xx response. Carries the parsed error message
+    (when the API returned one) so command functions can show the user
+    something meaningful instead of a raw traceback.
+    """
+
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"[{status_code}] {message}")
+
+
+class NotLoggedInError(Exception):
+    """Raised when a command needs an API key but none is stored yet."""
+
+
+@dataclass
+class Client:
+    base_url: str
+    api_key: str
+    timeout_seconds: int = 30
+
+    def _headers(self, idempotency_key: str | None = None) -> dict:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        return headers
+
+    def _request(self, method: str, path: str, idempotency_key=None, **kwargs) -> Any:
+        url = f"{self.base_url.rstrip('/')}{path}"
+        try:
+            resp = requests.request(
+                method,
+                url,
+                headers=self._headers(idempotency_key),
+                timeout=self.timeout_seconds,
+                **kwargs,
+            )
+        except requests.ConnectionError as e:
+            raise RaceAPIError(0, f"Could not reach {self.base_url}: {e}") from e
+        except requests.Timeout as e:
+            raise RaceAPIError(0, f"Request timed out after {self.timeout_seconds}s") from e
+
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+                message = (
+                    body.get("message")
+                    or body.get("detail")
+                    or str(body)
+                )
+            except ValueError:
+                message = resp.text or f"HTTP {resp.status_code}"
+            raise RaceAPIError(resp.status_code, message)
+
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+
+    def whoami(self) -> dict:
+        return self._request("GET", "/v1/api-keys/whoami/")
+
+    def list_pods(self) -> list:
+        """
+        Real response shape: {"status": "success", "data": [...]}, not a
+        bare array — unwrap here so cli.py never has to know about this
+        envelope, matching the plan: cli.py works with clean Python
+        values, api_client.py absorbs the API's actual wire format.
+        """
+        result = self._request("GET", "/v1/gpu/pod-list/")
+        return result.get("data", []) if result else []
+
+    def list_gpus(self) -> list:
+        """
+        GPUListAPIView returns Response(serializer.data) directly -- a
+        bare array, NOT wrapped in {"status", "data"} like PodListAPIView.
+        Confirmed against the literal current return statement in
+        gpu_list_view.py, not assumed from field-name patterns (an
+        earlier version of this method wrongly assumed the wrapper and
+        crashed against a real server with AttributeError).
+        """
+        return self._request("GET", "/v1/gpu/gpu-list/") or []
+
+    def list_templates(self) -> list:
+        """
+        TemplateListAPIView returns Response(serializer.data) directly --
+        a bare array, confirmed against the literal current return
+        statement in template_view.py (same pattern as GPUListAPIView,
+        both differ from PodListAPIView's {"status","data"} wrapper).
+        """
+        return self._request("GET", "/v1/gpu/templates/") or []
+
+    def get_pod_status(self, pod_id: str) -> dict:
+        return self._request("GET", f"/v1/gpu/deploy-status/?pod_id={pod_id}")
+
+    def deploy_pod(
+        self,
+        slice_id: str,
+        template_id: str | None = None,
+        custom_template_id: str | None = None,
+        disk_size: int = 50,
+        pod_name: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict:
+        """
+        idempotency_key: a client-generated UUID for THIS deploy attempt.
+        Callers should generate ONE key per logical deploy intent and
+        reuse it across retries of that same attempt (see cli.py's
+        `deploy` command) — a fresh key per retry would defeat the whole
+        point, since the server relies on seeing the SAME key again to
+        recognize "this is a retry of something I already handled," not
+        a brand new deploy.
+        """
+        payload = {
+            "slice_id": slice_id,
+            "disk_size": disk_size,
+        }
+        if template_id:
+            payload["template_id"] = template_id
+        if custom_template_id:
+            payload["custom_template_id"] = custom_template_id
+        if pod_name:
+            payload["pod_name"] = pod_name
+
+        return self._request(
+            "POST", "/v1/gpu/start-pod/", json=payload, idempotency_key=idempotency_key
+        )
+
+    def pause_pod(self, pod_id: str) -> dict:
+        return self._request("POST", "/v1/gpu/pause-pod/", json={"pod_id": pod_id})
+
+    def resume_pod(self, pod_id: str) -> dict:
+        return self._request("POST", "/v1/gpu/resume-pod/", json={"pod_id": pod_id})
+
+    def terminate_pod(self, pod_id: str) -> dict:
+        # TerminatePodAPIView only implements post(), not delete() --
+        # confirmed against the real view source. DELETE is the more
+        # conventional REST verb for this action, but this API doesn't
+        # follow that convention here.
+        return self._request("POST", "/v1/gpu/terminate-pod/", json={"pod_id": pod_id})
+
+
+def get_client() -> Client:
+    """
+    Builds a Client from stored config/credentials. Raises
+    NotLoggedInError (never a bare KeyError/AttributeError) if no key is
+    stored — every command function calls this first and lets that
+    exception propagate to a single, consistent "please run race login"
+    message, rather than each command handling the missing-key case
+    separately in a slightly different way.
+    """
+    api_key = config.load_api_key()
+    if not api_key:
+        raise NotLoggedInError("Not logged in. Run 'race login' first.")
+    return Client(base_url=config.get_base_url(), api_key=api_key)
+
+
+def new_idempotency_key() -> str:
+    return str(uuid.uuid4())

race_ai-0.1.0/race_cli/cli.py

@@ -0,0 +1,445 @@
+"""
+race CLI — thin command layer. Every command: parse args, call
+api_client, print a clean result. No business logic here — that lives
+entirely on the server. This mirrors the exact same view/service split
+used on the backend: commands are the "view" (user-facing surface),
+api_client.Client is the "service" (does the actual work).
+"""
+
+import sys
+import time
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from . import config
+from .api_client import NotLoggedInError, RaceAPIError, get_client, new_idempotency_key
+
+app = typer.Typer(help="Race Engineering GPU cloud CLI")
+console = Console()
+
+
+def _fail(message: str) -> None:
+    """Print an error and exit non-zero — every command's single error path."""
+    typer.secho(f"Error: {message}", fg=typer.colors.RED, err=True)
+    raise typer.Exit(code=1)
+
+
+@app.command()
+def login(
+    api_key: str = typer.Option(
+        None,
+        "--key",
+        help="Your API key (rk_...). If omitted, you'll be prompted (input hidden).",
+    ),
+    base_url: str = typer.Option(
+        None, "--base-url", help="Override the API base URL (advanced/internal use)."
+    ),
+):
+    """
+    Store an API key for future commands. Generate one first via the
+    web dashboard or `POST /v1/api-keys/` while logged in there — this
+    command does NOT create a key, only stores one you already have.
+    """
+    if base_url:
+        config.set_base_url(base_url)
+
+    if not api_key:
+        api_key = typer.prompt("API key", hide_input=True)
+
+    if not api_key.startswith("rk_"):
+        _fail("That doesn't look like a valid API key (should start with 'rk_').")
+
+    # Validate the key actually works BEFORE storing it — storing a
+    # typo'd/invalid key silently would mean every later command fails
+    # with a confusing 401, far from where the actual mistake happened.
+    config.save_api_key(api_key)
+    try:
+        client = get_client()
+        who = client.whoami()
+    except RaceAPIError as e:
+        config.delete_api_key()  # don't leave a known-bad key stored
+        _fail(f"Key validation failed, not saved: {e.message}")
+        return
+
+    typer.secho(
+        f"✓ Logged in as {who.get('email') or who.get('user_id', 'unknown')} "
+        f"(key: {who.get('key_name', 'unnamed')})",
+        fg=typer.colors.GREEN,
+    )
+
+
+@app.command()
+def logout():
+    """Remove the locally stored API key. Does NOT revoke the key server-side."""
+    config.delete_api_key()
+    typer.secho("✓ Logged out (local key removed).", fg=typer.colors.GREEN)
+
+
+@app.command()
+def deploy(
+    slice_id: str = typer.Option(..., "--gpu", help="GPU slice id to deploy on."),
+    template_id: str = typer.Option(None, "--template", help="Template id."),
+    custom_template_id: str = typer.Option(None, "--custom-template"),
+    disk_size: int = typer.Option(50, "--disk", help="Disk size in GB."),
+    name: str = typer.Option(None, "--name", help="Optional pod name."),
+):
+    """Deploy a new GPU pod."""
+    if not template_id and not custom_template_id:
+        _fail("Provide either --template or --custom-template.")
+
+    try:
+        client = get_client()
+    except NotLoggedInError as e:
+        _fail(str(e))
+        return
+
+    # ONE idempotency key for this whole deploy intent, reused across
+    # retries below — not regenerated per attempt. See api_client.py's
+    # deploy_pod docstring for why that distinction matters.
+    idempotency_key = new_idempotency_key()
+
+    attempts = 3
+    last_error = None
+    for attempt in range(attempts):
+        try:
+            result = client.deploy_pod(
+                slice_id=slice_id,
+                template_id=template_id,
+                custom_template_id=custom_template_id,
+                disk_size=disk_size,
+                pod_name=name,
+                idempotency_key=idempotency_key,
+            )
+            # StartPodAPIView has two distinct success shapes, confirmed
+            # against its real source:
+            #   async (custom template / spot): has pod_id + deploy_state,
+            #     container not up yet — poll `race status <pod_id>` next.
+            #   synchronous (built-in template): has container_id/web_url/
+            #     ssh_command directly, no pod_id/deploy_state at all —
+            #     the pod is already up, nothing to poll.
+            pod_id = result.get("pod_id")
+            if pod_id:
+                typer.secho(f"✓ Deploy started — pod_id={pod_id}", fg=typer.colors.GREEN)
+                typer.echo(f"  status: {result.get('deploy_state', result.get('status'))}")
+                typer.echo(f"  run 'race status {pod_id}' to check progress")
+            else:
+                typer.secho("✓ Pod deployed and ready", fg=typer.colors.GREEN)
+                if result.get("web_url"):
+                    typer.echo(f"  url: {result['web_url']}")
+                if result.get("ssh_command"):
+                    typer.echo(f"  ssh: {result['ssh_command']}")
+            return
+        except RaceAPIError as e:
+            last_error = e
+            # Only network-layer failures (status_code 0, from
+            # api_client's ConnectionError/Timeout handling) are safe to
+            # retry automatically — a real 4xx/5xx from the server is a
+            # definitive answer, not a transient blip, and retrying it
+            # would just get the same rejection again.
+            if e.status_code != 0:
+                break
+
+    _fail(f"Deploy failed: {last_error.message}")
+
+
+@app.command(name="list")
+def list_pods():
+    """List your GPU pods."""
+    try:
+        client = get_client()
+        pods = client.list_pods()
+    except NotLoggedInError as e:
+        _fail(str(e))
+        return
+    except RaceAPIError as e:
+        _fail(e.message)
+        return
+
+    if not pods:
+        typer.echo("No pods found.")
+        return
+
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("POD ID", style="dim")
+    table.add_column("NAME")
+    table.add_column("STATUS")
+    table.add_column("GPU")
+
+    for pod in pods:
+        status = pod.get("status", "")
+        deploy_progress = pod.get("deploy_progress")
+        if deploy_progress:
+            pct = deploy_progress.get("progress_percent")
+            status = f"{status} ({pct}%)" if pct is not None else status
+        table.add_row(str(pod.get("id", "")), pod.get("name", ""), status, pod.get("gpu", ""))
+
+    console.print(table)
+
+
+@app.command()
+def gpus():
+    """List available GPUs and their slice IDs (use a slice_id with 'race deploy --gpu')."""
+    try:
+        client = get_client()
+        gpu_list = client.list_gpus()
+    except NotLoggedInError as e:
+        _fail(str(e))
+        return
+    except RaceAPIError as e:
+        _fail(e.message)
+        return
+
+    if not gpu_list:
+        typer.echo("No GPUs found.")
+        return
+
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("SLICE ID", style="dim")
+    table.add_column("GPU")
+    table.add_column("VRAM")
+    table.add_column("RATE/HR")
+    table.add_column("REGION")
+
+    for gpu in gpu_list:
+        name = gpu.get("name", "")
+        slices = gpu.get("slices")
+        # slices may be a single dict, a list, or absent, depending on
+        # auth/context — normalize defensively rather than assume one shape.
+        if isinstance(slices, dict):
+            slices = [slices]
+        for s in slices or []:
+            slice_id = s.get("slice_id", s.get("id"))
+            table.add_row(
+                str(slice_id),
+                name,
+                f"{s.get('memory', '?')}GB",
+                f"₹{s.get('hourly_rate', '?')}",
+                s.get("region", ""),
+            )
+
+    if table.row_count == 0:
+        typer.echo("No available GPU slices found.")
+        return
+
+    console.print(table)
+
+
+@app.command()
+def templates():
+    """List built-in templates you can deploy (use a template_id with 'race deploy --template')."""
+    try:
+        client = get_client()
+        template_list = client.list_templates()
+    except NotLoggedInError as e:
+        _fail(str(e))
+        return
+    except RaceAPIError as e:
+        _fail(e.message)
+        return
+
+    # Only built-in templates can currently be deployed via API key/CLI
+    # (custom templates are rejected at deploy time with a 400) — showing
+    # them here would let a user pick an option that's guaranteed to fail.
+    builtin_only = [t for t in template_list if t.get("template_type") == "builtin"]
+
+    if not builtin_only:
+        typer.echo("No built-in templates found.")
+        return
+
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("TEMPLATE ID", style="dim")
+    table.add_column("NAME")
+    table.add_column("CATEGORY")
+
+    for t in builtin_only:
+        table.add_row(
+            str(t.get("id", "")),
+            t.get("name", ""),
+            t.get("category") or "—",
+        )
+
+    console.print(table)
+
+
+@app.command()
+def status(pod_id: str = typer.Argument(..., help="Pod id.")):
+    """Check a pod's deploy/status."""
+    try:
+        client = get_client()
+        result = client.get_pod_status(pod_id)
+    except NotLoggedInError as e:
+        _fail(str(e))
+        return
+    except RaceAPIError as e:
+        _fail(e.message)
+        return
+
+    deploy_state = result.get("deploy_state") or result.get("status")
+    typer.echo(f"status: {deploy_state}")
+
+    # web_url/ssh_command/container_id only ever appear when the server
+    # reports "ready" (two of the eleven real response shapes this
+    # endpoint can return) — every other shape omits them entirely, so
+    # .get(...) (never bare ["..."]) is required here, not optional.
+    if result.get("message"):
+        typer.echo(f"message: {result['message']}")
+    if result.get("web_url"):
+        typer.echo(f"url: {result['web_url']}")
+    if result.get("ssh_command"):
+        typer.echo(f"ssh: {result['ssh_command']}")
+    if result.get("progress_percent") is not None:
+        typer.echo(f"progress: {result['progress_percent']}%")
+    if result.get("error"):
+        typer.echo(f"error: {result['error']}")
+
+
+@app.command()
+def pause(pod_id: str = typer.Argument(...)):
+    """Pause a running pod."""
+    try:
+        client = get_client()
+        client.pause_pod(pod_id)
+    except NotLoggedInError as e:
+        _fail(str(e))
+        return
+    except RaceAPIError as e:
+        _fail(e.message)
+        return
+    typer.secho(f"✓ Pod {pod_id} paused.", fg=typer.colors.GREEN)
+
+
+@app.command()
+def resume(pod_id: str = typer.Argument(...)):
+    """Resume a paused pod."""
+    try:
+        client = get_client()
+        result = client.resume_pod(pod_id)
+    except NotLoggedInError as e:
+        _fail(str(e))
+        return
+    except RaceAPIError as e:
+        _fail(e.message)
+        return
+    typer.secho(f"✓ Pod {pod_id} resumed.", fg=typer.colors.GREEN)
+    if result.get("web_url"):
+        typer.echo(f"  url: {result['web_url']}")
+    if result.get("ssh_command"):
+        typer.echo(f"  ssh: {result['ssh_command']}")
+    resume_state = result.get("resume_state")
+    if resume_state and resume_state != "ready":
+        typer.echo(f"  status: {resume_state} — run 'race status {pod_id}' to check progress")
+
+
+@app.command()
+def terminate(
+    pod_id: str = typer.Argument(...),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+):
+    """Terminate a pod. Irreversible — asks for confirmation unless --yes."""
+    if not yes:
+        confirmed = typer.confirm(f"Terminate pod {pod_id}? This cannot be undone.")
+        if not confirmed:
+            typer.echo("Cancelled.")
+            return
+
+    try:
+        client = get_client()
+        client.terminate_pod(pod_id)
+    except NotLoggedInError as e:
+        _fail(str(e))
+        return
+    except RaceAPIError as e:
+        _fail(e.message)
+        return
+    typer.secho(f"✓ Pod {pod_id} terminated.", fg=typer.colors.GREEN)
+
+
+@app.command(hidden=True)
+def himanshu():
+    """(hidden) You found it."""
+    scenes = [
+        """
+┌─ TODO ──────────────────┐
+│ [x] Setup project       │
+│ [x] Fix dependency hell │
+│ [ ] Write actual code   │
+│ [ ] Make it work        │
+│ [ ] Write tests (lol)   │
+│ [ ] Deploy              │
+└──────────────────────────┘
+   "I'll sleep early today."
+   Me at 2:37 AM: 👁️  👁️
+                    ▽
+""",
+        """
+┌──────────── TERMINAL ────────────┐
+│ $ python app.py                  │
+│ ❌ Error: unexpected indent      │
+│ $ fix_indent.py                  │
+│ ✅ No errors!                     │
+│ $ python app.py                  │
+│ ❌ Error: something else          │
+└───────────────────────────────────┘
+     🦆  "Have you tried talking
+          to the duck?"
+""",
+        """
+┌──────────── CHATGPT ─────────────┐
+│ 🤖 Here's the fix:                │
+│   1. Update version               │
+│   2. Clear cache                  │
+│   3. Restart server               │
+│   4. Pray 🙏                      │
+└────────────────────────────────────┘
+        😐   "It works on my
+       /|\\    machine."
+       / \\
+""",
+        """
+╔═══════════ PRODUCTION ════════════╗
+║      🔥  SERVER DOWN  🔥          ║
+║          HTTP 500 💀              ║
+╚════════════════════════════════════╝
+  git push --force
+  Oops.
+  git reflog
+""",
+        """
+┌──────── FINAL STATUS ────────┐
+│  Code:        ✅              │
+│  Tests:       ❌              │
+│  Production:  💀              │
+│  Sleep:       ❌              │
+│  Coffee:      ☕☕☕           │
+│  Sanity:      -404            │
+└────────────────────────────────┘
+        STILL ALIVE...
+           ( •_•)
+          <)   )╯
+           /   \\
+""",
+    ]
+    for scene in scenes:
+        typer.echo(scene.strip("\n"))
+        time.sleep(1.1)
+
+    typer.secho(
+        "\n  H I M A N S H U",
+        fg=typer.colors.BRIGHT_MAGENTA,
+        bold=True,
+    )
+    typer.echo("  Sev-1 incident report: engineer spent 6 hours building auth,")
+    typer.echo("  idempotency, and a CLI — then spent 45 minutes demanding")
+    typer.echo("  a talking GPU easter egg. Root cause: unlimited creativity,")
+    typer.echo("  zero adult supervision. Status: resolved, mostly by accident.")
+    typer.echo("  postmortem action item: give this man a raise. 🫡\n")
+
+
+def main():
+    app()
+
+
+if __name__ == "__main__":
+    main()

race_ai-0.1.0/race_cli/config.py

@@ -0,0 +1,70 @@
+"""
+Local config + secure credential storage for the race CLI.
+
+Design: the API key is NEVER written to a plaintext dotfile. It's stored
+via the `keyring` package, which delegates to the OS's own credential
+store (macOS Keychain, Windows Credential Manager, Linux Secret Service /
+kwallet) — the same category of protection your browser or SSH agent
+uses for saved credentials. A dotfile like ~/.race/credentials would be
+plaintext, readable by any process running as that user, and a common
+target for credential-stealing malware; the OS keychain is not.
+
+The base URL (which server to talk to) is NOT a secret, so it's fine to
+store in a plain config file.
+"""
+
+import json
+from pathlib import Path
+
+import keyring
+
+_SERVICE_NAME = "race-cli"
+_KEYRING_USERNAME = "api_key"  # keyring stores secrets per (service, username)
+
+_CONFIG_DIR = Path.home() / ".race"
+_CONFIG_FILE = _CONFIG_DIR / "config.json"
+
+DEFAULT_BASE_URL = "https://api.raceengineering.ai"
+
+
+def get_base_url() -> str:
+    if _CONFIG_FILE.exists():
+        try:
+            data = json.loads(_CONFIG_FILE.read_text())
+            return data.get("base_url", DEFAULT_BASE_URL)
+        except (json.JSONDecodeError, OSError):
+            # Corrupt or unreadable config file — fall back to the
+            # default rather than crashing every single CLI invocation
+            # over a bad local file the user can just regenerate.
+            return DEFAULT_BASE_URL
+    return DEFAULT_BASE_URL
+
+
+def set_base_url(url: str) -> None:
+    _CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    data = {}
+    if _CONFIG_FILE.exists():
+        try:
+            data = json.loads(_CONFIG_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            data = {}
+    data["base_url"] = url
+    _CONFIG_FILE.write_text(json.dumps(data, indent=2))
+
+
+def save_api_key(raw_key: str) -> None:
+    keyring.set_password(_SERVICE_NAME, _KEYRING_USERNAME, raw_key)
+
+
+def load_api_key() -> str | None:
+    return keyring.get_password(_SERVICE_NAME, _KEYRING_USERNAME)
+
+
+def delete_api_key() -> None:
+    try:
+        keyring.delete_password(_SERVICE_NAME, _KEYRING_USERNAME)
+    except keyring.errors.PasswordDeleteError:
+        # Nothing was stored — deleting a non-existent credential is not
+        # an error condition from the CLI user's perspective ("logout"
+        # when already logged out should just succeed quietly).
+        pass

race_ai-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+