Metadata-Version: 2.4
Name: sun-cli
Version: 0.1.0
Summary: CLI for the Sun audio course generation API.
Keywords: audio,cli,course,podcast,sun
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Multimedia :: Sound/Audio
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: typer<1.0,>=0.12
Description-Content-Type: text/markdown

# sun-cli

Command-line client for the Sun audio course generation API. Generate audio
courses from a prompt, poll for completion, and download per-lecture MP3
files — all from one binary.

## Install

```bash
pip install sun-cli
```

Or with `uv`:

```bash
uv tool install sun-cli
```

Verify:

```bash
sun --help
```

Python 3.10+ is required. macOS and Linux are first-class.

## Quickstart

```bash
# 1. Log in (email + password).
sun login

# 2. Mint a personal API token — secret is printed once.
sun tokens create laptop

# 3. Generate a course and wait for it to finish.
sun courses create \
  --prompt "A 30-minute course on the French Revolution" \
  --duration-minutes 30 \
  --wait

# 4. Download the manifest + per-lecture MP3 files.
sun courses get <JOB_ID> --out ./french-revolution
ls ./french-revolution
# course.json
# lectures/001-causes.mp3
# lectures/002-...mp3
```

## Commands

```
sun login [--email EMAIL] [--password PASSWORD]
sun logout
sun whoami

sun tokens create NAME [--no-save]
sun tokens list [--json]
sun tokens revoke NAME|ID

sun courses create [--prompt TEXT] [--input PATH] [--duration-minutes N]
                   [--voice-id ID] [--wait] [--json]
sun courses status JOB_ID [--json]
sun courses get    JOB_ID [--json] [--out DIR]
```

## Authentication

The CLI uses two distinct auth modes:

- **Token management** (`sun tokens *`) — uses the Supabase JWT persisted by
  `sun login`. A leaked API token cannot mint replacements.
- **Everything else** (`sun courses *`, `sun whoami`) — uses a personal API
  token of the form `sk_live_...`.

The Supabase URL and anon key are auto-discovered from the Sun API's public
`/v1/public/auth-config` endpoint, so end users only need an email and
password.

Credentials are stored at `~/.config/sun/credentials.json` with mode `0600`.

## Configuration

| Variable | Purpose |
| --- | --- |
| `SUN_API_BASE_URL` | Override the default API base URL (e.g. for staging or local dev). |
| `SUN_TOKEN` | Use this API token instead of the credentials file. CI mode. |
| `SUPABASE_URL`, `SUPABASE_ANON_KEY` | Optional override for `sun login` only. The CLI auto-discovers these otherwise. |

## Rate limits

Default: 3 successful-or-in-flight generations per rolling 24h per user
(configurable per user). Failed generations don't count against the quota.

The server returns `429` with `Retry-After` and `X-RateLimit-*` headers when
the limit is hit.

## License

See LICENSE in the source repository.
