Artists Management

The Artists Management module provides the core functionality for interacting with artist entities within the Recoup platform via the CLI. It serves as a bridge between the user and the /api/artists backend endpoints, allowing users to list, filter, and validate artist accounts for subsequent workflows such as content creation.

This module is integrated into the main CLI entry point and works alongside other modules like Content Management to ensure artists are properly configured and ready for automated tasks.
Sources: src/bin.ts:24, src/commands/artists.ts:33-35

Command Architecture

The artists command group is built using the commander library. It defines a primary command artists and a sub-command list for retrieving artist data. The command handles user input, processes optional flags for filtering, and delegates network requests to a centralized HTTP client.

The diagram shows the flow from a user command through the artist command logic to the API and back to the console output.
Sources: src/commands/artists.ts:5-28, src/client.ts:8-12

The List Command

The list command fetches artists associated with the authenticated account. It supports specific filtering options to narrow results by organization or specific account IDs.

Sources: src/commands/artists.ts:7-10

Data Interaction and API Integration

The module communicates with the /api/artists endpoint using a GET request. The client automatically injects the x-api-key header for authentication and handles the transformation of optional flags into query parameters.

Request Flow

When a user executes the list command, the following logic is applied:

1. Parameter Extraction: The CLI checks for the presence of org or account options.
2. API Call: A GET request is dispatched to /api/artists.
3. Error Handling: If the API returns an error status or the network request fails, the system prints a formatted error and exits with code 1.

This sequence diagram illustrates how flags like --org are mapped to API parameters during a request.
Sources: src/commands/artists.ts:12-16, src/client.ts:13-25, tests/commands/artists.test.ts:46-50

Data Models

The artist data structure returned by the API and processed by the CLI contains identity and metadata fields used for display and further processing.

Artist Object Fields

Sources: src/commands/artists.ts:23-25, tests/commands/artists.test.ts:34-36

Content Pipeline Integration

Artists are the central entities for the content creation pipeline. Before content can be generated, an artist must be validated to ensure all necessary assets (like files or metadata) are present.

Validation Logic

The content validate command specifically targets an artist by their ID to check readiness.

The flow shows how the validation status affects the content pipeline.
Sources: src/commands/content/validateCommand.ts:13-17

Creation Logic

When triggering content creation via recoup content create, the --artist <id> flag is mandatory, linking the generated content (e.g., videos, lipsync) directly to the artist's account.
Sources: src/commands/content/createCommand.ts:12-15

Output Formatting

The CLI provides two primary ways to view artist data, managed by the output.ts utility:

1. Table View (Default): A human-readable column-aligned table displaying ID, Name, and Label.
2. JSON View: Enabled with the --json flag, this provides the raw array of artist objects for programmatic use.

// Example of the artist list response structure
[
  {
    "account_id": "a1",
    "name": "Artist One",
    "label": "Label A"
  }
]

Sources: src/commands/artists.ts:20-27, src/output.ts:20-30

Summary

The Artists Management module is a foundational component of the Recoup CLI, enabling users to discover and filter artist entities. By integrating with the centralized HTTP client and output formatters, it ensures consistent interaction with artist data, which serves as the prerequisite for more complex workflows like content validation and automated media generation.