Documentation Index
Fetch the complete documentation index at: https://developers.recoupable.com/llms.txt
Use this file to discover all available pages before exploring further.
The Recoup CLI (@recoupable/cli) wraps the Recoup API for terminal-first workflows. It’s available as a global npm package and comes pre-installed in sandbox environments.
The CLI is in beta. The commands listed below are what’s shipped today (v0.1.13). For research workflows and most content operations, call the REST API directly — the CLI is gradually catching up.Agents: if a command isn’t listed below, don’t retry — fall back to the corresponding REST endpoint linked under each command. Install
npm install -g @recoupable/cli
Authenticate
Set your API key as an environment variable:
export RECOUP_API_KEY=your-api-key
Configuration
| Variable | Required | Default | Description |
|---|
RECOUP_API_KEY | Yes | — | Your Recoup API key |
RECOUP_API_URL | No | https://recoup-api.vercel.app | API base URL override |
--json for machine-readable output and --help for usage info.
Commands
whoami
Show the authenticated account. See GET /api/accounts/id.
recoup whoami
recoup whoami --json
orgs
List organizations. See GET /api/organizations.
recoup orgs list
recoup orgs list --account <accountId>
artists
List artists. See GET /api/artists.
recoup artists list
recoup artists list --org <orgId>
recoup artists list --account <accountId>
notifications
Send a notification email to the authenticated account. See POST /api/notifications.
recoup notifications --subject "Pulse Report" --text "Here's your weekly summary."
recoup notifications --subject "Update" --html "<h1>Report</h1><p>Details here.</p>"
| Flag | Required | Description |
|---|
--subject <text> | Yes | Email subject line |
--text <body> | No | Plain text or Markdown body |
--html <body> | No | Raw HTML body (takes precedence over --text) |
--cc <email> | No | CC recipient (repeatable) |
--room-id <id> | No | Room ID for a chat link in the email footer |
--account <accountId> | No | Send to a specific account (org keys only) |
chats
Manage chats. See GET /api/chats and POST /api/chats.
recoup chats list
recoup chats create --name "My Topic"
recoup chats create --name "My Topic" --artist <artistId>
sandboxes
Manage sandboxes. See GET /api/sandboxes and POST /api/sandboxes.
recoup sandboxes list
recoup sandboxes create
recoup sandboxes create --command "ls -la"
tasks
Check background task status. See GET /api/tasks/runs.
recoup tasks status --run <runId>
songs
Run AI music analysis. See POST /api/songs/analyze and GET /api/songs/analyze/presets.
recoup songs presets
recoup songs analyze --preset catalog_metadata --audio https://example.com/track.mp3
recoup songs analyze --prompt "Describe the production style" --audio https://example.com/track.mp3
--preset or --prompt is required. The other flags are optional.
| Flag | Required | Description |
|---|
--preset <name> | Conditional | Curated analysis preset. Required when --prompt is omitted. |
--prompt <text> | Conditional | Custom text prompt. Required when --preset is omitted. |
--audio <url> | No | Public URL to the audio file (MP3, WAV, FLAC). Some presets analyze the audio file; others (like catalog_metadata) work from metadata alone. |
--max-tokens <n> | No | Max tokens to generate (default 512). |
content
Content creation pipeline — generate AI-powered social videos for artists.
List templates
Validate an artist
Check that an artist has the required assets before creating content. See GET /api/content/validate.
recoup content validate --artist <artistAccountId>
Estimate cost
Preview estimated cost and duration before kicking off the pipeline. See POST /api/content/estimate.
recoup content estimate --artist <artistAccountId>
recoup content estimate --artist <artistAccountId> --template <name>
Create content
Run the full content-creation pipeline for an artist. See POST /api/content/create.
recoup content create --artist <artistAccountId>
recoup content create --artist <artistAccountId> --template <name> --lipsync --upscale
| Flag | Required | Description |
|---|
--artist <id> | Yes | Artist account ID |
--template <name> | No | Template name (default: random) |
--lipsync | No | Enable lipsync mode |
--upscale | No | Enable upscaling |
--caption-length <n> | No | Max caption length in characters |
For finer-grained control (individual image, video, caption, transcription, edit, upscale, or analyze operations), call the content REST endpoints directly. Those primitives aren’t yet exposed as individual CLI subcommands. 
