Organizations Directory

Relevant source files

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

• src/commands/orgs.ts
• __tests__/commands/orgs.test.ts
• src/client.ts
• src/bin.ts
• src/output.ts
• CLAUDE.md

The Organizations Directory is a core component of the Recoup CLI designed to manage and list organizational entities associated with a user's account. It acts as a management layer that allows users to view high-level structural data, often used to filter other resources like artists.

The directory is implemented as a subcommand within the main recoup binary. It interfaces with the Recoup REST API via a specialized HTTP client to retrieve organization data, which can then be rendered as human-readable tables or machine-readable JSON.

Sources: src/commands/orgs.ts:1-29, src/bin.ts:11-30, CLAUDE.md:20-25

Command Architecture

The Organizations Directory is structured using the commander library. It is registered as the orgs command in the main entry point and contains a list subcommand for data retrieval.

Logic Flow and Data Retrieval

When a user executes the command, the CLI performs several steps:

1. Parses command-line options (e.g., --json, --account).
2. Constructs request parameters.
3. Invokes the central HTTP client to fetch data from the /api/organizations endpoint.
4. Processes the API response and routes it to the appropriate formatter based on user flags.

The following diagram illustrates the flow from user input to the final display:

The flow shows how the CLI handles request parameterization and conditional output formatting.
Sources: src/commands/orgs.ts:6-25, src/client.ts:8-37, tests/commands/orgs.test.ts:41-43

Technical Implementation

API Interaction

The directory relies on the get method from the project's internal HTTP client. This client automatically handles authentication by injecting the x-api-key from environment variables and constructs the full URL using the configured base URL.

Component	Description	Reference
Endpoint	/api/organizations	src/commands/orgs.ts
Method	GET	src/client.ts
Auth Header	x-api-key	src/client.ts
Base URL	https://recoup-api.vercel.app (Default)	CLAUDE.md

Sources: src/client.ts:8-37, src/commands/orgs.ts:12, CLAUDE.md:27-28

Command Options

The list command supports specific flags to modify its behavior:

Option	Type	Description
--json	Boolean	Returns the raw API response as formatted JSON.
--account <accountId>	String	Filters organizations associated with a specific account ID.

Sources: src/commands/orgs.ts:7-9, tests/commands/orgs.test.ts:54-56

Data Model

The CLI expects a specific structure for organization objects returned by the API. This data is mapped to table columns during standard output.

Field Name	Table Label	Description
organization_id	ID	The unique identifier for the organization.
organization_name	NAME	The display name of the organization.

Sources: src/commands/orgs.ts:19-22, tests/commands/orgs.test.ts:35-37

Output Formatting

The Organizations Directory utilizes a shared output.ts utility to ensure consistency.

• Table Mode: Uses printTable to create column-aligned text. If the API returns an empty list, it outputs "No results."
• JSON Mode: Uses printJson to output a stringified version of the data with a 2-space indent.
• Error Handling: Catches exceptions during the request or parsing phase and uses printError to log the message to stderr and exit with status code 1.

The sequence shows the interaction between the command logic and the output utility for both successful and failed states.
Sources: src/output.ts:1-55, src/commands/orgs.ts:15-26, tests/commands/orgs.test.ts:63-65

Conclusion

The Organizations Directory provides a streamlined interface for viewing organizational hierarchies within the Recoup platform. By integrating with the central HTTP client and output utilities, it maintains high performance and consistent behavior across the CLI suite.