Skip to main content
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
Verify it works: 
recoup whoami
Get an API key from the API Keys page or use the agent signup for instant key generation.

​
Configuration

VariableRequiredDefaultDescription
RECOUP_API_KEYYes—Your Recoup API key
RECOUP_API_URLNohttps://api.recoupable.comAPI base URL override
All commands support --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>"
FlagRequiredDescription
--subject <text>YesEmail subject line
--text <body>NoPlain text or Markdown body
--html <body>NoRaw HTML body (takes precedence over --text)
--cc <email>NoCC recipient (repeatable)
--room-id <id>NoRoom ID for a chat link in the email footer
--account <accountId>NoSend 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
One of --preset or --prompt is required. The other flags are optional.
FlagRequiredDescription
--preset <name>ConditionalCurated analysis preset. Required when --prompt is omitted.
--prompt <text>ConditionalCustom text prompt. Required when --preset is omitted.
--audio <url>NoPublic 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>NoMax tokens to generate (default 512).

​
content

Content creation pipeline — generate AI-powered social videos for artists.

​
List templates

recoup content 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
FlagRequiredDescription
--artist <id>YesArtist account ID
--template <name>NoTemplate name (default: random)
--lipsyncNoEnable lipsync mode
--upscaleNoEnable upscaling
--caption-length <n>NoMax 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.