Skip to main content
The Recoup CLI (@recoupable/cli) is a command-line wrapper around the Recoup API. It’s available as a global npm package and is pre-installed in sandbox environments.

​
Installation

npm install -g @recoupable/cli

​
Authentication

Set your API key as an environment variable. You can get a key from the API Keys page. 
export RECOUP_API_KEY=your-api-key
Verify it works: 
recoup whoami

​
Configuration

VariableRequiredDefaultDescription
RECOUP_API_KEYYes—Your Recoup API key
RECOUP_API_URLNohttps://recoup-api.vercel.appAPI base URL override
All commands support --json for machine-readable output and --help for usage info.

​
whoami

Show the authenticated account. See GET /api/accounts/id. 
recoup whoami
recoup whoami --json

​
orgs

Manage organizations. See GET /api/organizations. 
recoup orgs list
recoup orgs list --account <accountId>
recoup orgs list --json

​
artists

Manage artists. See GET /api/artists. 
recoup artists list
recoup artists list --org <orgId>
recoup artists list --account <accountId>
recoup artists list --json

​
notifications

Send a notification email to the authenticated account’s email address. The recipient is automatically resolved from your API key — no need to specify a to address. 
recoup notifications --subject "Pulse Report" --text "Here's your weekly summary."
recoup notifications --subject "Update" --cc manager@example.com --text "New release scheduled."
recoup notifications --subject "Weekly Pulse" --html "<h1>Pulse Report</h1><p>BVB release planning is <strong>active</strong>.</p>"
recoup notifications --subject "Pulse Report" --account <accountId> --text "Here's your weekly summary."
FlagRequiredDescription
--subject <text>YesEmail subject line
--text <body>NoPlain text or Markdown body (rendered as HTML)
--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)
This command wraps POST /api/notifications.

​
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>
recoup chats list --json

​
sandboxes

Manage sandboxes. See GET /api/sandboxes and POST /api/sandboxes. 
recoup sandboxes list
recoup sandboxes create
recoup sandboxes create --command "ls -la"
recoup sandboxes list --json

​
tasks

Check the status of background task runs. See GET /api/tasks/runs. 
recoup tasks status --run <runId>
recoup tasks status --run <runId> --json
FlagRequiredDescription
--run <id>YesTrigger.dev run ID

​
content

Content-creation pipeline commands. Generate AI-powered social videos for artists.

​
List templates

List available content templates. See GET /api/content/templates. 
recoup content templates
recoup content templates --json

​
Validate artist

Check that an artist has the required assets (face-guide, songs, context files) before creating content. See POST /api/content/validate. 
recoup content validate --artist <artistAccountId>
recoup content validate --artist <artistAccountId> --json
FlagRequiredDescription
--artist <id>YesArtist account ID

​
Estimate cost

Preview the estimated cost and duration for a content run without starting it. See POST /api/content/estimate. 
recoup content estimate --artist <artistAccountId>
recoup content estimate --artist <artistAccountId> --template <name> --json
FlagRequiredDescription
--artist <id>YesArtist account ID
--template <name>NoTemplate name (default: random)
--lipsyncNoEnable lipsync mode
--upscaleNoEnable upscaling

​
Create content

Trigger the full content-creation pipeline. Returns a run ID you can check with recoup tasks status. See POST /api/content. 
recoup content create --artist <artistAccountId>
recoup content create --artist <artistAccountId> --template <name> --lipsync --upscale
recoup content create --artist <artistAccountId> --json
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