CLI Entrypoint (bin.ts)

Relevant source files

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

• src/bin.ts
• __tests__/bin.test.ts
• package.json
• tsup.config.ts
• CLAUDE.md
• src/commands/content.ts
• src/commands/songs.ts

The src/bin.ts file serves as the primary entrypoint for the Recoup platform CLI. It initializes the command-line interface, configures global settings like the version and description, and aggregates various subcommands into a single unified executable structure.

The CLI is built using the commander library and is designed to provide a thin wrapper over the Recoup REST endpoints, allowing users to interact with the platform directly from their terminal.
Sources: src/bin.ts:1-12, CLAUDE.md:16-24

Architecture and Command Registration

The entrypoint utilizes a modular architecture where specific functional domains are encapsulated in separate command files within the src/commands/ directory. These are then imported and attached to the main program instance.

System Initialization

The initialization process involves:

1. Metadata Retrieval: Reading package.json to extract the current version of the CLI.
2. Program Configuration: Setting the name to recoup and applying descriptions.
3. Command Loading: Registering high-level command modules.

The diagram above illustrates the sequential flow of CLI initialization from execution to the parsing of user arguments.
Sources: src/bin.ts:14-31, package.json:5-7

Registered Subcommands

The following table summarizes the command modules registered in the main entrypoint:

Command Group	Description	Source Module
whoami	Show account identity	src/commands/whoami.js
artists	Manage artist entities	src/commands/artists.js
chats	Interface with chat systems	src/commands/chats.js
songs	Song analysis tools	src/commands/songs.js
notifications	Send alerts/emails	src/commands/notifications.js
sandboxes	Environment management	src/commands/sandboxes.js
orgs	Organization management	src/commands/orgs.js
tasks	Progress tracking	src/commands/tasks.js
content	Content-creation pipeline	src/commands/content.js

Sources: src/bin.ts:4-29

Build and Execution Lifecycle

The bin.ts file is written in TypeScript and undergoes a transformation process to become an executable Node.js script.

Compilation Strategy

The project uses tsup to bundle the TypeScript source into a CommonJS (CJS) distribution format. This ensures compatibility for global installation via npm install -g. The configuration injects a shebang (#!/usr/bin/env node) at the top of the resulting file to allow direct execution.

Versioning Logic

The entrypoint dynamically determines its version by reading the package.json file relative to the execution path. This ensures that recoup --version always matches the published package metadata.

// Path resolution and version extraction in bin.ts
const pkgPath = join(__dirname, "..", "package.json");
const { version } = JSON.parse(readFileSync(pkgPath, "utf-8"));

program
  .name("recoup")
  .version(version);

Sources: src/bin.ts:14-21, __tests__/bin.test.ts:7-22

Command Tree Structure

Most commands registered in bin.ts act as namespaces for further sub-commands. For instance, the content command registered in bin.ts serves as a parent for templates, validate, estimate, and create.

Conclusion

src/bin.ts functions as the central nervous system of the Recoup CLI. By leveraging commander for command routing and tsup for cross-platform compatibility, it provides a structured and maintainable gateway for all platform interactions. It handles the critical bridge between the filesystem (metadata), the command definitions, and the user's terminal input.