docs/cli.mdx at main · recoupable/docs

title	CLI
description	Install and use the Recoup CLI to interact with the platform from your terminal.

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

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

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

Flag	Required	Description
`--subject <text>`	Yes	Email subject line
`--text <body>`	No	Plain text or Markdown body (rendered as HTML)
`--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)

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

Flag	Required	Description
`--run <id>`	Yes	Trigger.dev run ID

research

Music industry research — streaming metrics, audience demographics, playlist placements, competitive analysis, and web intelligence. All data is accessed through your RECOUP_API_KEY.

Artist-scoped commands (like metrics, audience, similar) accept an artist name or a Recoup artist ID (UUID). The API resolves the artist automatically. If the name is ambiguous (multiple matches), the API returns the top results for disambiguation.

Search for an artist

recoup research "Drake"
recoup research "Phoebe Bridgers" --json

See GET /api/research.

Lookup by platform URL

Find an artist from a Spotify URL, Apple Music link, or any platform ID.

recoup research lookup "https://open.spotify.com/artist/3TVXtAsR1Inumwj472S9r4"
recoup research lookup "3TVXtAsR1Inumwj472S9r4"

See GET /api/research/lookup.

Artist profile and career

recoup research profile "Drake"
recoup research career "Drake"
recoup research insights "Drake"

Subcommand	Description	API endpoint
`profile`	Full artist profile — bio, genres, social URLs, label	`GET /api/research/profile`
`career`	Career timeline and key milestones	`GET /api/research/career`
`insights`	AI-generated observations and trends	`GET /api/research/insights`

Streaming and social metrics

Get platform-specific metrics over time. Supports 14 platforms.

recoup research metrics "Drake" --source spotify
recoup research metrics "Drake" --source instagram
recoup research metrics "Drake" --source tiktok
recoup research metrics "Drake" --source youtube_channel

Valid --source values: spotify, instagram, tiktok, twitter, facebook, youtube_channel, youtube_artist, soundcloud, deezer, twitch, line, melon, wikipedia, bandsintown.

See GET /api/research/metrics.

Audience and geography

recoup research audience "Drake"
recoup research audience "Drake" --platform tiktok
recoup research audience "Drake" --platform youtube
recoup research cities "Drake"

Subcommand	Description	API endpoint
`audience`	Age, gender, country breakdown. `--platform`: `instagram` (default), `tiktok`, `youtube`	`GET /api/research/audience`
`cities`	Top cities by listener concentration	`GET /api/research/cities`

Social URLs

Get all social and streaming links for an artist.

recoup research urls "Drake"

See GET /api/research/urls.

Instagram posts

Get an artist's top Instagram posts and reels by engagement.

recoup research instagram-posts "Drake"

See GET /api/research/instagram-posts.

Competitive landscape

recoup research similar "Drake"
recoup research similar "Drake" --audience high --genre high --limit 20

Configuration options: --audience, --genre, --mood, --musicality (values: high, medium, low).

See GET /api/research/similar.

Playlists

recoup research playlists "Drake"
recoup research playlists "Drake" --platform applemusic
recoup research playlists "Drake" --editorial
recoup research playlists "Drake" --status past --since 2025-01-01
recoup research playlists "Drake" --sort followers --limit 50

Flag	Description
`--platform <p>`	`spotify` (default), `applemusic`, `deezer`, `amazon`, `youtube`
`--editorial`	Only editorial playlists
`--status <s>`	`current` (default) or `past`
`--since <date>`	Filter by date (YYYY-MM-DD)
`--sort <field>`	Sort results (e.g., `followers`)
`--limit <n>`	Max results

See GET /api/research/playlists.

Discography

recoup research albums "Drake"
recoup research tracks "Drake"

See GET /api/research/albums and GET /api/research/tracks.

Track details

Get metadata for a specific track — look up by name or Spotify URL.

recoup research track "God's Plan"
recoup research track "https://open.spotify.com/track/2grjqo0Frpf2..."

See GET /api/research/track.

Playlist and curator details

Get metadata for a specific playlist or its curator.

recoup research playlist spotify 37i9dQZF1DXcBWIGoYBM5M
recoup research curator spotify 1

See GET /api/research/playlist and GET /api/research/curator.

Discover artists

Find artists by criteria — country, genre, listener ranges, growth rate.

recoup research discover --country US --spotify-listeners 100000 500000
recoup research discover --genre 86 --sort weekly_diff.sp_monthly_listeners

Flag	Description
`--country <code>`	ISO country code (US, BR, GB, etc.)
`--genre <id>`	Genre ID (use `recoup research genres` to list)
`--spotify-listeners <min> <max>`	Monthly listener range
`--sort <field>`	Sort field (e.g., `weekly_diff.sp_monthly_listeners`)
`--limit <n>`	Max results

See GET /api/research/discover.

Milestones

Get an artist's activity feed — playlist adds, chart entries, and notable events.

recoup research milestones "Drake"
recoup research milestones "Drake" --json

See GET /api/research/milestones.

Venues

Get venues an artist has performed at, including capacity and location.

recoup research venues "Drake"
recoup research venues "Drake" --json

See GET /api/research/venues.

Rank

Get an artist's global Chartmetric ranking.

recoup research rank "Drake"
recoup research rank "Drake" --json

See GET /api/research/rank.

Charts

Get global chart positions for a platform. NOT artist-scoped — returns the full chart.

recoup research charts --platform spotify
recoup research charts --platform spotify --country US
recoup research charts --platform applemusic --country GB --interval weekly --json

Flag	Required	Description
`--platform <name>`	Yes	Chart platform (spotify, applemusic, tiktok, youtube, itunes, shazam)
`--country <code>`	No	ISO country code (US, GB, DE, etc.)
`--interval <interval>`	No	Time interval (e.g. daily, weekly)
`--type <type>`	No	Chart type (varies by platform)
`--latest`	No	Return only the most recent chart

See GET /api/research/charts.

Radio stations

List radio stations tracked by Chartmetric.

recoup research radio
recoup research radio --json

See GET /api/research/radio.

Reference data

recoup research genres
recoup research festivals

See GET /api/research/genres and GET /api/research/festivals.

Web research

Search the web for narrative context, press coverage, and cultural information that structured data doesn't cover.

recoup research web "Drake brand partnerships sync licensing"
recoup research web "Phoebe Bridgers fan community psychographics"

See POST /api/research/web.

Deep research report

Comprehensive multi-source research that synthesizes information from across the web into a cited report.

recoup research report "Drake"
recoup research report "Tell me everything about Phoebe Bridgers — bio, streaming metrics, fan base, competitive landscape, and revenue opportunities"

See POST /api/research/deep.

People search

Search for people in the music industry — artists, managers, A&R reps, producers. Returns profiles with LinkedIn data.

recoup research people "A&R reps at Atlantic Records"
recoup research people "music managers in Los Angeles R&B"

See POST /api/research/people.

Extract URL

Extract clean markdown content from any public URL. Handles JavaScript-heavy pages and PDFs.

recoup research extract "https://en.wikipedia.org/wiki/Drake_(musician)" --objective "biography and discography"
recoup research extract "https://open.spotify.com/artist/..." --full-content

Accepts up to 10 URLs per call.

See POST /api/research/extract.

Enrich

Get structured data about any entity from web research. Provide a description and a JSON schema — get typed data back with citations.

recoup research enrich "Drake rapper" --schema '{"properties": {"real_name": {"type": "string"}, "label": {"type": "string"}, "hometown": {"type": "string"}}}'

Processors: base (fast, default), core (balanced), ultra (comprehensive).

See POST /api/research/enrich.

Using Recoup artist IDs

Artist IDs are supported on artist-scoped commands (see the note above). Example:

recoup research metrics de05ba8c-7e29-4f1a-93a7-3635653599f6 --source spotify

Workflow example: full artist research

# Pull structured data (all by name, run in parallel)
recoup research metrics "Phoebe Bridgers" --source spotify --json
recoup research audience "Phoebe Bridgers" --json
recoup research cities "Phoebe Bridgers" --json
recoup research similar "Phoebe Bridgers" --audience high --genre high --json
recoup research playlists "Phoebe Bridgers" --editorial --json

# Add web context
recoup research web "Phoebe Bridgers biography career milestones" --json
recoup research web "Phoebe Bridgers fan community brand partnerships" --json

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

Flag	Required	Description
`--artist <id>`	Yes	Artist 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

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

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

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

FilesExpand file tree

cli.mdx

Latest commit

History