Metadata-Version: 2.4
Name: sun-cli
Version: 0.2.1
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
Provides-Extra: test
Requires-Dist: pytest<9,>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# sun-cli

Command-line client for the Sun audio generation API. Generate audio from a
prompt, poll for completion (or stream episodes as they finish), and download
the manifest plus per-episode MP3 + image files — all from one binary.

## Install

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

Or with `uv`:

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

Verify:

```bash
sun --help
sun --version    # prints "sun-cli <version>"
```

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 audio and wait for it to finish.
sun audio create \
  --prompt "A 30-minute course on the French Revolution" \
  --duration-minutes 30 \
  --wait

# 4. Download the manifest + per-episode MP3 + image files.
sun audio get <JOB_ID> --out ./french-revolution
ls ./french-revolution
# overview.json
# cover.png
# episodes/001-causes.mp3
# episodes/001-causes.png
# episodes/002-...mp3
# ...
```

For streaming (download each episode the moment its audio is ready), pair
`--partial` with a polling loop or register a webhook with `--callback-url`:

```bash
sun audio create --prompt "..." --callback-url https://your.handler/hook --json

# or, polling:
sun audio get <JOB> --partial --out ./out   # safe before SUCCESS; skips episodes still generating
```

## Commands

```
sun --version
sun --help

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 audio create [--prompt TEXT] [--input PATH] [--duration-minutes N]
                 [--voice-id ID] [--callback-url URL] [--wait] [--json]
sun audio status JOB_ID [--json]
sun audio get    JOB_ID [--partial] [--json] [--out DIR]
```

`sun courses ...` still works as a hidden alias for backwards compatibility —
it prints a one-line deprecation warning on stderr and runs the same command.
Prefer `sun audio` in new scripts.

## 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 audio *`, `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.
