sun-cli 0.2.1

CLI for the Sun audio course generation API.

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

pip install sun-cli

Or with uv:

uv tool install sun-cli

Verify:

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

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

Quickstart

# 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:

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.