CLI - Recoup

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

Variable	Required	Default	Description
`RECOUP_API_KEY`	Yes	—	Your Recoup API key
`RECOUP_API_URL`	No	`https://api.recoupable.dev`	API 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>

emails

Send an email to the authenticated account. See POST /api/emails.

recoup emails --subject "Pulse Report" --text "Here's your weekly summary."
recoup emails --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

One of --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

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

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.

​Install

​Authenticate

​Configuration

​Commands

​whoami

​orgs

​artists

​emails

​chats

​sandboxes

​tasks

​songs

​content

​List templates

​Validate an artist

​Estimate cost

​Create content

Install

Authenticate

Configuration

Commands

whoami

orgs

artists

emails

chats

sandboxes

tasks

songs

content

List templates

Validate an artist

Estimate cost

Create content