Architecture Overview

The Recoup CLI is a thin, specialized wrapper built on Node.js designed to interface with the Recoup platform's REST API. It serves as a command-line entry point for managing platform resources such as artists, chats, sandboxes, and content creation pipelines. The application follows a modular architecture where each command group is isolated into its own logical unit, all coordinated by a central entry point.

The CLI is built using the commander framework for command-line parsing, tsup for bundling into a CommonJS (CJS) format to ensure global installation compatibility, and native fetch (available in Node 22+) for HTTP communications.

Sources: CLAUDE.md:1-25, package.json:1-30, src/bin.ts:1-30

Core Components and Structure

The architecture is divided into three primary layers: the Entry Point/Routing layer, the Command Logic layer, and the Service/Utility layer.

Entry Point (Routing Layer)

The file src/bin.ts acts as the CLI entry point. It initializes the commander program, sets the version from package.json, and registers various subcommands. This structure allows the CLI to scale by simply adding new command modules to the main program.

Service Layer (HTTP Client)

The HTTP client in src/client.ts abstracts the interaction with the Recoup API. It handles authentication by injecting the x-api-key header derived from the RECOUP_API_KEY environment variable. It provides standardized get and post methods that handle URL parameter serialization, JSON body parsing, and error status mapping.

Sources: src/client.ts:1-68, CLAUDE.md:10-18

Data Flow

When a user executes a command, the data flows from the CLI interface, through a specific command handler, to the shared API client, and finally to the remote Recoup API.

Output and Formatting

The CLI provides two primary output modes managed by src/output.ts:

1. Plain Text/Table: The default mode for human readability, often using formatted tables or bulleted lists.
2. JSON: Enabled via the --json flag, providing raw, machine-readable data for script integration.

The system uses a printTable utility to align columns and a printError utility to standardize error reporting to stderr with an exit code of 1.

Sources: src/output.ts:1-60, CLAUDE.md:14-16

Build and Deployment Configuration

The project utilizes tsup for its build pipeline to compile TypeScript into a single-file CommonJS executable. This is critical for the npm install -g distribution model, ensuring the binary can run in various Node.js environments.

// 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:5-10

Conclusion

The Recoup CLI architecture emphasizes the Single Responsibility Principle (SRP) by isolating commands and utilizing a centralized client for API interactions. Its reliance on standard Node.js features and simple design patterns ensures it remains a lightweight, maintainable wrapper for the platform's API services.