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).
