Authentication Methods for API-Based CLI Harnesses in CLI-Anything

CLI-Anything supports two distinct authentication methods for its API-based CLI harnesses: OAuth 2.0 browser-based flows for services requiring delegated access, and Bearer token-based API keys or personal access tokens for the majority of integrations including Obsidian, Novita, and Mailchimp.

The CLI-Anything repository provides a collection of "agent-harness" modules that expose third-party service APIs as command-line interfaces. Understanding the supported authentication methods for API-based CLI harnesses is essential for securely connecting these tools to your accounts and automating workflows without exposing credentials in shell history or process lists.

OAuth 2.0 Browser-Based Flow

The OAuth 2.0 implementation provides secure, delegated access for services that require user authorization through a browser. Currently, the Zoom harness (cli-anything-zoom) utilizes this method exclusively according to the HKUDS/CLI-Anything source code.

Configuration and Token Storage

In zoom/agent-harness/cli_anything/zoom/core/auth.py, the auth setup subcommand stores the OAuth application credentials—client-id, client-secret, and redirect-uri—in a local JSON configuration file. The auth login subcommand launches a temporary local HTTP server on the specified redirect URI to capture the authorization code returned from the browser callback.

The implementation exchanges the authorization code for access and refresh tokens, then persists these tokens to disk for subsequent API calls.

Token Injection in API Requests

All authenticated requests include the token in an Authorization: Bearer <token> header. The zoom/agent-harness/cli_anything/zoom/utils/zoom_backend.py utility manages the injection of this header into every outgoing Zoom API request, ensuring transparent authentication for all CLI operations.

# Store OAuth application credentials

cli-anything-zoom auth setup \
  --client-id <YOUR_CLIENT_ID> \
  --client-secret <YOUR_CLIENT_SECRET> \
  --redirect-uri http://localhost:4199/callback

# Initiate browser flow and capture tokens

cli-anything-zoom auth login

# Verify authentication status

cli-anything-zoom auth status --json

API Key and Personal Access Token Authentication

The majority of CLI-Anything harnesses—including Obsidian, Novita, n8n, Mailchimp, MacroCLI, AnyGen, AdGuardHome, and Firefly III—use static API keys or personal access tokens (PATs).

Credential Input Methods

Each harness implements a consistent pattern for receiving credentials. The code reads the API key from three possible sources, checked in order of precedence:

• Command-line option: --api-key <TOKEN> (defined in Click option decorators)
• Environment variable: Service-specific variables like OBSIDIAN_API_KEY or FI_PAGETOKEN
• JSON configuration file: Local config files storing the token persistently

Request Header Construction

Regardless of the input method, the backend utilities inject the token into the Authorization: Bearer <key> header. In obsidian/agent-harness/cli_anything/obsidian/utils/obsidian_backend.py, the Obsidian harness constructs this header before dispatching requests to the Obsidian Local REST API. Similarly, novita/agent-harness/cli_anything/novita/utils/novita_backend.py handles Novita API authentication using the identical Bearer pattern.

For Firefly III, the firefly-iii/agent-harness/cli_anything/firefly_iii/utils/firefly_iii_backend.py specifically handles personal access tokens, while mailchimp/agent-harness/cli_anything/mailchimp/core/client.py extracts API keys and validates their presence before request execution.

# Obsidian: Direct command-line usage

cli-anything-obsidian --api-key MY_OBSIDIAN_TOKEN vault list

# Obsidian: Environment variable approach

export OBSIDIAN_API_KEY=MY_OBSIDIAN_TOKEN
cli-anything-obsidian vault list

# Novita: API key pattern

cli-anything-novita --api-key sk-abc123 model list

# Firefly III: Personal Access Token

export FI_PAGETOKEN=YOUR_PAT
cli-anything-firefly-iii account list

Error Handling for Missing Credentials

When no valid credentials are detected, the harness raises a clear RuntimeError indicating the specific action required. For OAuth-based harnesses, the error directs users to run auth setup or auth login. For API-key harnesses, the error specifies the required command-line flag or environment variable name, as implemented in the parameter validation logic of macrocli/agent-harness/cli_anything/macrocli/core/parameterize.py and similar backend validation routines.

Summary

• CLI-Anything implements two authentication patterns: OAuth 2.0 browser flows and Bearer token-based API keys.
• OAuth 2.0 powers the Zoom integration, using local HTTP callbacks and refresh token persistence in zoom/core/auth.py.
• API keys support the majority of harnesses (Obsidian, Novita, Mailchimp, Firefly III, n8n) via --api-key flags, environment variables, or config files.
• All authenticated requests use Authorization: Bearer <token> headers, constructed in respective backend utilities like obsidian_backend.py and novita_backend.py.
• Missing credentials trigger explicit RuntimeError exceptions with actionable setup instructions.

Frequently Asked Questions

How do I switch from using an environment variable to a config file for API keys?

Most harnesses check for environment variables first, then fall back to configuration files. To use a config file exclusively, omit the environment variable and run the harness's configure command if available, or manually create the JSON config file in the harness's configuration directory as referenced in mailchimp/core/client.py or similar backend implementations. The code typically loads the file using standard JSON parsing and extracts the api_key field.

Does CLI-Anything support interactive password prompts instead of command-line flags?

The current implementations in the repository primarily support non-interactive authentication methods. API keys must be provided via --api-key arguments, environment variables, or pre-configured JSON files. There is no interactive password prompt in the analyzed authentication flows for cli-anything-obsidian or cli-anything-zoom, as the n8n/agent-harness/cli_anything/n8n/n8n_cli.py and similar CLI entry points define these as required Click options or environment variables only.

How long do OAuth tokens remain valid in the Zoom harness?

The Zoom OAuth implementation stores both access tokens and refresh tokens. Access tokens typically expire after one hour according to Zoom's API specifications, but the harness handles token refresh automatically using the stored refresh token when you run subsequent commands, as managed in zoom/agent-harness/cli_anything/zoom/core/auth.py. Users do not need to manually re-authenticate unless the refresh token expires or is revoked.

Can I use the same API key authentication pattern for custom harnesses?

Yes. The pattern used in obsidian/agent-harness/cli_anything/obsidian/utils/obsidian_backend.py and novita/agent-harness/cli_anything/novita/utils/novita_backend.py provides a reusable template: accept --api-key via Click options (defined in files like n8n/agent-harness/cli_anything/n8n/n8n_cli.py), check for environment variable fallbacks, validate presence, and inject the Authorization: Bearer header in the backend request utility before dispatching to the target API endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}