Global Flags & Options

The Recoup CLI provides a set of global flags and environment-based configuration options that control the behavior of all subcommands. These options primarily manage output formatting, API authentication, and endpoint targeting, ensuring a consistent experience across different functional modules such as artists, chats, and sandboxes.

Sources: src/bin.ts:1-31, README.md:1-55, CLAUDE.md:1-25

Output Configuration

The CLI supports multiple output formats to accommodate both human readability and machine-readable automation.

The --json Flag

All commands within the Recoup platform support the --json flag. When this flag is present, the CLI bypasses standard text formatting and table rendering in favor of raw, pretty-printed JSON output. This is particularly useful for piping CLI output to tools like jq or for consumption by other scripts.

Sources: README.md:46-47, CLAUDE.md:17-17, src/output.ts

Output Logic Flow

The following diagram illustrates how the CLI determines the formatting logic based on the presence of the global JSON flag.

The CLI uses a centralized output utility to handle these transitions. For instance, in the sandboxes list command, the logic checks for opts.json before deciding to use printTable.

Sources: src/commands/sandboxes.ts:10-18, src/output.ts

Environment-Based Configuration

Global behavior is heavily influenced by environment variables, which the CLI uses for authentication and network configuration.

Sources: README.md:49-55, CLAUDE.md:21-25

Authentication Mechanism

The CLI implements a thin wrapper around the native Node.js fetch API. Every request, whether GET or POST, automatically injects the global API key into the request headers.

Shared Command Options

While most flags are command-specific, several patterns appear globally across different command groups to maintain parity.

Identification Flags

Many commands (such as artists, orgs, and notifications) support flags to narrow the scope of the request to specific accounts or organizations:

• --account <id>: Specifies a specific account ID to act upon.
• --org <id>: Filters results or targets a specific organization.

Sources: tests/commands/artists.test.ts:46-70, tests/commands/notifications.test.ts:125-140

Processing Options

Commands that involve long-running tasks or complex analysis often share similar operational flags:

• --audio <url>: Used in songs analyze to provide input data.
• --batch <count>: Used in content create to trigger parallel processing.

Sources: src/commands/songs.ts:8-8, src/commands/content/createCommand.ts:16-16

Error Handling & Global Exit Codes

The CLI employs a global error handling strategy. When an operation fails—whether due to network issues, invalid API keys, or server-side errors—the CLI uses a standard printError function. This function logs the error message to stderr and terminates the process with exit code 1.

Sources: src/output.ts, tests/output.test.ts:58-69

Summary

Global flags and options in the Recoup CLI are designed for simplicity and interoperability. By leveraging the --json flag and environment variables like RECOUP_API_KEY, users can seamlessly integrate the CLI into automated workflows while maintaining a consistent interface across the diverse set of provided commands.