Introduction & Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CLAUDE.md
• src/bin.ts
• src/client.ts
• src/output.ts
• package.json
• tsup.config.ts

The @recoupable/cli is a Command-Line Interface (CLI) designed for interacting with the Recoup platform. It serves as a thin wrapper around the Recoup REST API, allowing developers and users to manage artists, chats, sandboxes, and content creation pipelines directly from their terminal. The CLI is built with TypeScript and designed for global installation via npm.

Sources: README.md:1-5, CLAUDE.md:1-5, package.json:2-10

Architecture & Framework

The CLI is architected using a modular command structure based on the commander library. It prioritizes the Single Responsibility Principle (SRP), where each command group is managed in a separate file. The application is bundled using tsup into a CommonJS (CJS) format to ensure compatibility across various Node.js environments.

Core Components

• Entrypoint (src/bin.ts): Initializes the Commander program, sets the version from package.json, and registers all subcommands.
• HTTP Client (src/client.ts): A central utility using native fetch to handle GET and POST requests to the Recoup API.
• Output Handler (src/output.ts): Manages data presentation, supporting plain text tables, formatted JSON, and standardized error reporting.
• Configuration: Utilizes environment variables for authentication and API endpoint selection.

Sources: CLAUDE.md:11-20, src/bin.ts:1-35, tsup.config.ts:3-12

System Data Flow

The following diagram illustrates how a user command flows through the CLI to the Recoup API:

The CLI acts as a bridge between the local shell environment and the remote Recoup API.
Sources: CLAUDE.md:14-22, src/bin.ts:15-33, src/client.ts:10-57

Configuration & Environment

The CLI requires an API key for authentication. This is passed via the x-api-key header in every HTTP request.

Variable	Required	Description	Default Value
RECOUP_API_KEY	Yes	API key from Recoup Developer Dashboard	N/A
RECOUP_API_URL	No	Base URL for the Recoup API	https://recoup-api.vercel.app

Sources: README.md:46-51, CLAUDE.md:16-25, src/client.ts:27,51

Command Structure

The CLI organizes functionality into several primary command groups. Every command supports a --json flag for machine-readable output.

Command Groups

Command Group	Description	Key Subcommands
whoami	Account identification	N/A
artists	Artist management	list
chats	Communication	list, create
sandboxes	Isolated environments	list, create
songs	Music analysis	analyze, presets
content	Creation pipeline	templates, create, validate
tasks	Background processing	status

Sources: README.md:21-44, src/bin.ts:15-30, src/commands/content.ts:1-12

API Interaction Sequence

The following sequence diagram demonstrates the authentication and request flow for a typical "list" command:

The HTTP client automatically attaches necessary headers and handles base URL resolution before reaching the API.
Sources: src/client.ts:10-38, README.md:10-25, CLAUDE.md:16-17

Build & Distribution

The project uses tsup for bundling and vitest for testing. The final distribution is an executable Node.js script.

// tsup.config.ts configuration snippet
export default defineConfig({
  entry: ["src/bin.ts"],
  format: ["cjs"],
  target: "node22",
  banner: {
    js: "#!/usr/bin/env node",
  },
});

Sources: tsup.config.ts:3-12, package.json:11-16

Summary

The @recoupable/cli provides a structured, extensible interface for the Recoup platform. By centralizing API logic in a native fetch client and separating command logic into dedicated modules, the architecture remains maintainable and test-driven. It effectively transforms complex REST interactions into simple terminal commands suitable for both manual use and automated workflows in sandboxes.

Sources: CLAUDE.md:8-30, README.md:1-5