Configuration & Authentication
Relevant source files
The following files were used as context for generating this wiki page:
The Recoup CLI is a thin wrapper over the Recoup platform's REST endpoints. Its configuration and authentication systems are designed to be simple and environment-driven, relying on specific environment variables to manage security credentials and API routing.
The primary purpose of the configuration layer is to provide the HTTP client with the necessary metadata (API keys and Base URLs) to communicate securely with the Recoup API. Authentication is handled via a static API key passed in the request headers, ensuring that every command executed by the user is authorized against their Recoup account.
Sources: CLAUDE.md:1-25, README.md:1-10
Authentication Mechanism
Authentication in the Recoup CLI is strictly managed through the RECOUP_API_KEY environment variable. This key is used to identify the user and authorize requests to the platform.
API Key Implementation
The CLI retrieves the API key using a specialized configuration utility. When making HTTP requests, this key is injected into the x-api-key header. If the key is missing or invalid, the API returns an error which the CLI then handles and displays to the user.
The diagram above illustrates the flow of the API key from environment variables through the configuration utility to the final HTTP request headers.
Sources: src/client.ts:25-28, src/client.ts:51-54, CLAUDE.md:14-15, tests/client.test.ts:19-33
Authentication Setup
Users are required to set the API key in their shell environment to authenticate:
| Method | Command |
|---|---|
| Temporary (Session) | export RECOUP_API_KEY=your-api-key |
| Persistent (zsh) | echo 'export RECOUP_API_KEY=your-api-key' >> ~/.zshrc |
| Persistent (bash) | echo 'export RECOUP_API_KEY=your-api-key' >> ~/.bashrc |
Sources: README.md:13-24
Environment Configuration
The CLI behavior can be modified using environment variables. These variables control where the CLI sends requests and how it identifies itself to the server.
Configuration Variables
| Variable | Required | Default Value | Description |
|---|---|---|---|
RECOUP_API_KEY | Yes | N/A | Your Recoup API key used for x-api-key header. |
RECOUP_API_URL | No | https://recoup-api.vercel.app | The base URL for the Recoup API. |
Sources: README.md:52-57, CLAUDE.md:20-22
API Base URL Logic
The CLI uses a centralized configuration utility to resolve the API endpoint. It prioritizes the RECOUP_API_URL environment variable if provided, falling back to the production Vercel URL otherwise.
// Example logic derived from configuration handling
const baseUrl = getBaseUrl(); // Returns RECOUP_API_URL or default
const url = new URL(path, baseUrl);
Sources: src/client.ts:13-15, CLAUDE.md:20-22
Secure Request Handling
The internal HTTP client (implemented in src/client.ts) ensures that configuration and authentication are applied consistently across all GET and POST operations.
Header Injection
Every request automatically includes the following headers:
x-api-key: Populated viagetApiKey()from environment variables.Content-Type: Set toapplication/jsonfor all requests.
Sources: src/client.ts:24-28, src/client.ts:50-54
Error Handling & Validation
The client validates both the HTTP response status and the application-level status returned in the JSON body. If response.ok is false or the JSON status field equals "error", the client throws an Error containing the message from the API.
The client architecture prioritizes strict validation of API responses to ensure the user is notified of authentication or configuration failures immediately.
Sources: src/client.ts:33-36, src/client.ts:59-62, tests/client.test.ts:55-75
Verification
To verify that the configuration and authentication are correctly set up, the CLI provides a whoami command. This command performs a GET request to /api/accounts/id. A successful response confirms that the RECOUP_API_KEY is valid and the RECOUP_API_URL is reachable.
Sources: README.md:26-31, src/bin.ts:25
The authentication and configuration systems provide a low-overhead, environment-centric approach to managing CLI state, ensuring that credentials are kept out of the source code while remaining easily configurable for different environments.