Installation & Quick Start
Relevant source files
The following files were used as context for generating this wiki page:
The Recoup CLI is a command-line interface designed to interact with the Recoup platform. It acts as a thin wrapper over the platform's REST endpoints, allowing developers to manage artists, chats, sandboxes, and content creation pipelines directly from their terminal.
This guide covers the prerequisites, installation steps, and initial configuration required to begin using the recoup command.
Sources: README.md:1-5, CLAUDE.md:1-5, CLAUDE.md:25-25
Installation
The CLI is distributed as a Node.js package and is intended for global installation within environments such as sandboxes or local development machines.
Prerequisites
- Node.js: The CLI targets Node 22.
- Package Manager:
npmis used for global installation, whilepnpmis used for local development and dependency management.
Sources: CLAUDE.md:4-4, CLAUDE.md:15-15, tsup.config.ts:6-6
Global Installation
To install the CLI globally on your system, execute the following command:
npm install -g @recoupable/cli
Once installed, the recoup command becomes available as the primary entry point for all platform interactions.
Sources: README.md:9-11, package.json:6-8
Development Setup
If you are contributing to the project or building from source, follow these steps:
- Install dependencies:
pnpm install - Build the project:
pnpm build(Usestsupto generate a CJS distribution) - Run tests:
pnpm test(Usesvitest)
Sources: CLAUDE.md:8-12, package.json:13-16
Authentication & Configuration
The CLI requires an API key to authenticate requests against the Recoup API. This is handled via environment variables that the internal HTTP client reads at runtime.
Configuration Variables
| Variable | Required | Description | Default |
|---|---|---|---|
RECOUP_API_KEY | Yes | Your Recoup platform API key | N/A |
RECOUP_API_URL | No | API base URL for requests | https://recoup-api.vercel.app |
Sources: README.md:43-48, CLAUDE.md:16-16, CLAUDE.md:21-22
Setting the API Key
You must export the RECOUP_API_KEY in your shell session or add it to your profile (e.g., ~/.zshrc or ~/.bashrc) to persist it:
export RECOUP_API_KEY=your-api-key
Sources: README.md:15-26
Request Flow
The following diagram illustrates how the CLI authenticates a command request using the configured environment variables.
The CLI uses native fetch (Node 22) to send requests. Every request automatically includes the x-api-key header derived from the RECOUP_API_KEY environment variable.
Sources: CLAUDE.md:15-16, src/client.ts:24-28, src/client.ts:51-55
Quick Start Verification
After installation and configuration, verify your setup by checking the authenticated account identity.
Verify Identity
Run the following command to retrieve your account ID:
recoup whoami
If the authentication is successful, the CLI will output your account ID. You can also request raw data using the global --json flag.
recoup whoami --json
Sources: README.md:28-36, src/bin.ts:24-24
Command Architecture
The CLI is built using the commander framework and organizes functionality into subcommands.
The src/bin.ts file serves as the central entry point where all command modules are registered.
Sources: src/bin.ts:1-35, CLAUDE.md:14-14
Global Flags
Most commands support a common set of options to control output and behavior:
--json: Outputs the raw API response as formatted JSON instead of plain text or tables.--version: Displays the current version of@recoupable/cli.
Sources: README.md:65-67, src/bin.ts:21-21, CLAUDE.md:17-17
Summary
The Recoup CLI provides a streamlined way to interact with the platform. By installing the package via npm and configuring the RECOUP_API_KEY, users can access a wide range of features from account management to automated content creation. The tool is designed for compatibility with Node 22 and uses a standard subcommand structure for ease of use.
Sources: CLAUDE.md:1-25, README.md:1-48