sun-cli 0.2.0

CLI for the Sun audio course generation API.

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

pip install sun-cli

Or with uv:

uv tool install sun-cli

Verify:

sun --help

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