> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recoupable.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# CLI
> Install the Recoup CLI and interact with the platform from your terminal.
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](/api-reference) 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
```bash theme={null}
npm install -g @recoupable/cli
```
## Authenticate
Set your API key as an environment variable:
```bash theme={null}
export RECOUP_API_KEY=your-api-key
```
Verify it works:
```bash theme={null}
recoup whoami
```
Get an API key from the [API Keys page](https://chat.recoupable.dev/keys) or use the [agent signup](/agents) 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`](/api-reference/accounts/id).
```bash theme={null}
recoup whoami
recoup whoami --json
```
### orgs
List organizations. See [`GET /api/organizations`](/api-reference/organizations/list).
```bash theme={null}
recoup orgs list
recoup orgs list --account
```
### artists
List artists. See [`GET /api/artists`](/api-reference/artists/list).
```bash theme={null}
recoup artists list
recoup artists list --org
recoup artists list --account
```
### emails
Send an email to the authenticated account. See [`POST /api/emails`](/api-reference/emails/create).
```bash theme={null}
recoup emails --subject "Pulse Report" --text "Here's your weekly summary."
recoup emails --subject "Update" --html "Report
Details here.
"
```
| Flag | Required | Description |
| ----------------------- | -------- | ---------------------------------------------- |
| `--subject ` | Yes | Email subject line |
| `--text ` | No | Plain text or Markdown body |
| `--html ` | No | Raw HTML body (takes precedence over `--text`) |
| `--cc ` | No | CC recipient (repeatable) |
| `--room-id ` | No | Room ID for a chat link in the email footer |
| `--account ` | No | Send to a specific account (org keys only) |
### chats
Manage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/chats`](/api-reference/chat/create).
```bash theme={null}
recoup chats list
recoup chats create --name "My Topic"
recoup chats create --name "My Topic" --artist
```
### sandboxes
Manage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and [`POST /api/sandboxes`](/api-reference/sandboxes/create).
```bash theme={null}
recoup sandboxes list
recoup sandboxes create
recoup sandboxes create --command "ls -la"
```
### tasks
Check background task status. See [`GET /api/tasks/runs`](/api-reference/tasks/runs).
```bash theme={null}
recoup tasks status --run
```
### songs
Run AI music analysis. See [`POST /api/songs/analyze`](/api-reference/songs/analyze) and [`GET /api/songs/analyze/presets`](/api-reference/songs/analyze-presets).
```bash theme={null}
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 ` | Conditional | Curated analysis preset. Required when `--prompt` is omitted. |
| `--prompt ` | Conditional | Custom text prompt. Required when `--preset` is omitted. |
| `--audio ` | 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 ` | No | Max tokens to generate (default 512). |
***
## content
Content creation pipeline — generate AI-powered social videos for artists.
### List templates
```bash theme={null}
recoup content templates
```
### Validate an artist
Check that an artist has the required assets before creating content. See [`GET /api/content/validate`](/api-reference/content/validate).
```bash theme={null}
recoup content validate --artist
```
### Estimate cost
Preview estimated cost and duration before kicking off the pipeline. See [`POST /api/content/estimate`](/api-reference/content/estimate).
```bash theme={null}
recoup content estimate --artist
recoup content estimate --artist --template
```
### Create content
Run the full content-creation pipeline for an artist. See [`POST /api/content/create`](/api-reference/content/create).
```bash theme={null}
recoup content create --artist
recoup content create --artist --template --lipsync --upscale
```
| Flag | Required | Description |
| ---------------------- | -------- | -------------------------------- |
| `--artist ` | Yes | Artist account ID |
| `--template ` | No | Template name (default: random) |
| `--lipsync` | No | Enable lipsync mode |
| `--upscale` | No | Enable upscaling |
| `--caption-length ` | 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](/api-reference/content/generate-image) directly. Those primitives aren't yet exposed as individual CLI subcommands.