Local Development Setup

Relevant source files

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

• CLAUDE.md
• package.json
• tsconfig.json
• tsup.config.ts
• vitest.config.ts
• README.md
• src/client.ts

The Recoup CLI is a Node.js-based command-line interface designed to interact with the Recoup platform. It is built using TypeScript and the Commander.js framework, providing a thin wrapper over REST endpoints via native fetch.

Setting up the local development environment involves configuring the Node.js runtime, installing dependencies via pnpm, and configuring environment variables for API authentication. The project follows a Test-Driven Development (TDD) approach, requiring a functional test environment for local iterations.

Sources: CLAUDE.md:1-10, README.md:1-5

Prerequisites and Environment

The project is optimized for modern Node.js environments. The build target is specifically set to Node 22, and the project uses pnpm for dependency management.

System Requirements

Component	Requirement	Description
Runtime	Node.js v22	Target runtime for CJS distribution
Package Manager	pnpm	Recommended for dependency installation
Compiler	TypeScript ^5.7.0	Language used for development

Sources: package.json:20-25, tsup.config.ts:6-8, CLAUDE.md:12-16

Configuration

Developers must configure environment variables to authenticate with the Recoup API. These variables are read during execution to determine the API endpoint and provide necessary credentials.

Variable	Required	Default Value	Description
RECOUP_API_KEY	Yes	N/A	API key for x-api-key header
RECOUP_API_URL	No	https://recoup-api.vercel.app	Base URL for API requests

Sources: README.md:50-55, CLAUDE.md:25-30

Development Workflow

The development workflow is centered around building the source code from TypeScript to CommonJS (CJS) for compatibility with global installations and running tests using Vitest.

Core Commands

The following scripts are defined for standard development tasks:

pnpm install        # Install project dependencies
pnpm build          # Bundle project using tsup
pnpm test           # Execute test suite via vitest
pnpm lint           # Run ESLint with auto-fix
pnpm format         # Format source code using Prettier

Sources: package.json:11-17, CLAUDE.md:12-16

Build Pipeline

The project utilizes tsup for bundling. The configuration ensures that the output is executable as a CLI tool.

This diagram shows the transformation from TypeScript source files to the final executable CommonJS bundle.

Sources: tsup.config.ts:1-12, package.json:5-8

Project Architecture

The CLI is structured into several functional modules to maintain the Single Responsibility Principle (SRP).

Module Structure

• Entrypoint: src/bin.ts initializes the Commander.js program and registers subcommands.
• HTTP Client: src/client.ts manages fetch requests, headers, and error handling.
• Commands: Located in src/commands/, each file or directory corresponds to a specific command group (e.g., songs, sandboxes).
• Output: src/output.ts provides utility functions for formatting API responses as tables or JSON.

Sources: CLAUDE.md:18-24, src/bin.ts:1-15

Data Flow: API Request

When a developer executes a command, the internal flow follows a standard request-response pattern through the client.ts module.

This diagram illustrates how the CLI handles authentication and request execution via the internal client.

Sources: src/client.ts:1-55, CLAUDE.md:20-22

Testing Setup

Testing is a core part of the local development process. The project uses Vitest with a focus on mocking API calls to ensure commands behave correctly without making real network requests.

Test Configuration

The vitest.config.ts sets up the testing environment using Node.js as the global environment.

// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globals: true,
    environment: "node",
  },
});

Sources: vitest.config.ts:1-8

Mocking Strategy

Tests typically mock src/client.ts to simulate API responses. This allows for verifying command logic, flag handling, and output formatting.

Sources: tests/client.test.ts:1-10, tests/commands/content.test.ts:3-10

Conclusion

Setting up the Recoup CLI for local development requires Node 22 and pnpm. By configuring the RECOUP_API_KEY and utilizing the built-in tsup and vitest workflows, developers can efficiently build and test new features. The modular architecture ensures that adding new commands involves extending the src/commands directory and registering them in the main entrypoint.