Revenium CLI for Node.js

Unified CLI tools for Claude Code, Gemini CLI, Cursor IDE, GitHub Copilot, and Codex metering

A professional-grade set of CLI tools that configure automatic AI usage tracking for Claude Code, Gemini CLI, Cursor IDE, GitHub Copilot, and OpenAI Codex CLI. Features interactive setup wizards, OTLP telemetry, shell profile management with backup/restore, Cursor/Copilot sync engines with SHA-256 deduplication, and historical backfill with batch processing.

Features

• Five CLIs Unified - Claude Code, Gemini CLI, Cursor IDE, GitHub Copilot, and Codex metering in one package
• Interactive Setup Wizard - Guided configuration with shell profile auto-update and backup
• OTLP Telemetry - Standard OpenTelemetry log format with retry logic and exponential backoff
• Cursor Sync Engine - Continuous sync with SHA-256 deduplication, state persistence, and process locking
• Historical Backfill - Import past usage data with batch processing, dry-run mode, and date filtering
• Shell Management - Auto-detection (bash/zsh/fish), profile modification with timestamped backups
• Security - PII masking, restricted file permissions (0o600), safe shell escaping
• Programmatic API - Validation, OTLP client, health checks, masking, and shell detection

Architecture

@revenium/cli
|
|-- _core/                  Shared infrastructure across all CLIs
|   |-- api/
|   |   |-- otlp-client     OTLP HTTP client (retry, backoff, 30s timeout)
|   |   |-- retry-handler   Shared batch retry with exponential backoff
|   |   +-- health-check    Endpoint connectivity testing
|   |-- config/
|   |   |-- validator        API key, email, URL validation
|   |   +-- loader           Env file parsing, OTEL attribute decoding
|   |-- shell/
|   |   |-- detector         Shell type detection (bash/zsh/fish)
|   |   |-- escaping         Shell-safe value escaping per shell type
|   |   +-- profile-updater  Profile modification with backup/restore
|   |-- utils/
|   |   +-- masking          PII masking for API keys and emails
|   |-- types/               Core TypeScript interfaces
|   +-- constants            Shared defaults and paths
|
|-- claude-code/            Claude Code CLI (revenium-metering)
|   |-- cli/                 Commander entry point
|   |-- commands/            setup, status, test, backfill
|   |-- config/              ~/.claude/revenium.env loader/writer
|   +-- constants            Subscription tiers and cost multipliers
|
|-- gemini-cli/             Gemini CLI (revenium-gemini)
|   |-- cli/                 Commander entry point
|   |-- commands/            setup, status, test
|   |-- config/              ~/.gemini/revenium.env loader/writer (bash + fish)
|   +-- constants            Gemini-specific env vars
|
|-- cursor/                 Cursor IDE CLI (revenium-cursor)
|   |-- cli/                 Commander entry point
|   |-- commands/            setup, status, test, sync, reset, backfill
|   |-- config/              ~/.cursor/revenium/revenium.env loader/writer
|   |-- core/
|   |   |-- cursor-client    Cursor Admin API client (pagination, 30-day chunking)
|   |   +-- sync/
|   |       |-- scheduler    Sync cycle orchestration and watch mode
|   |       |-- state-manager Persistent sync state (JSON)
|   |       +-- deduplicator SHA-256 hash-based event deduplication
|   +-- transform/
|       +-- otlp-mapper      Cursor events -> OTLP log records
|
|-- copilot/                GitHub Copilot CLI (revenium-copilot)
|   |-- cli/                 Commander entry point
|   |-- commands/            setup, status, test, sync, reset, backfill
|   |-- config/              ~/.github-copilot/revenium/ loader/writer
|   |-- core/
|   |   |-- github-client    GitHub Copilot API client (28-day window)
|   |   +-- sync/
|   |       |-- scheduler    Sync cycle orchestration and watch mode
|   |       |-- state-manager Persistent sync state (JSON)
|   |       +-- deduplicator Natural key deduplication
|   +-- constants            Subscription tiers and env keys
|
+-- codex-cli/              OpenAI Codex CLI (revenium-codex)
    |-- cli/                 Commander entry point
    |-- commands/            setup, status, test, backfill
    |-- config/              ~/.codex/config.toml [otel] section
    +-- constants            Codex-specific paths and defaults

Data Flow

User runs CLI command
       |
       v
Interactive Setup (Inquirer prompts)
       |
       v
Validate inputs (API key hak_/rev_ prefix, email RFC, URL protocol)
       |
       v
Test endpoint connectivity (OTLP health check with latency)
       |
       v
Write config to tool-specific location:
  - Claude Code:      ~/.claude/revenium.env
  - Gemini CLI:       ~/.gemini/revenium.env
  - Cursor IDE:       ~/.cursor/revenium/revenium.env
  - GitHub Copilot:   ~/.github-copilot/revenium/revenium.env
  - Codex CLI:        ~/.codex/config.toml [otel] section
       |
       v
Update shell profile (bash/zsh/fish) with env vars
  - Creates timestamped backup before modification
  - Uses marker comments for idempotent updates
  - Keeps last 5 backups, cleans older ones

Cursor Sync Flow

revenium-cursor sync [--watch]
       |
       v
Load sync state from ~/.cursor/revenium/state.json
       |
       v
Acquire process lock (prevent concurrent syncs)
       |
       v
Fetch events from Cursor Admin API
  - Async generator with pagination
  - 30-day chunking for API limits
  - Retry with exponential backoff
       |
       v
Deduplicate via SHA-256 hash (up to 10,000 recent hashes)
       |
       v
Transform to OTLP log records (token counts, costs, billing)
       |
       v
Send to Revenium endpoint (retry on 5xx, 30s timeout)
       |
       v
Persist updated sync state (atomic write via temp file)
       |
       v (--watch mode)
Wait sync interval (default 5 min) -> repeat

Copilot Sync Flow

revenium-copilot sync [--watch]
       |
       v
Load sync state from ~/.github-copilot/revenium/state.json
       |
       v
Acquire process lock (prevent concurrent syncs)
       |
       v
Fetch usage data from GitHub Copilot API
  - Organization-level usage metrics
  - 28-day rolling window per request
  - Retry with exponential backoff
       |
       v
Deduplicate via natural key (day + language + editor)
       |
       v
Transform to OTLP log records (suggestions, acceptances, active users)
       |
       v
Send to Revenium endpoint (retry on 5xx, 30s timeout)
       |
       v
Persist updated sync state (atomic write via temp file)
       |
       v (--watch mode)
Wait sync interval (default 5 min) -> repeat

CLI Tools

| Binary | Tool | Commands | |--------|------|----------| | revenium-metering | Claude Code | setup status test backfill | | revenium-gemini | Gemini CLI | setup status test | | revenium-cursor | Cursor IDE | setup status test sync reset backfill | | revenium-copilot | GitHub Copilot | setup status test sync reset backfill | | revenium-codex | OpenAI Codex | setup status test backfill |

Installation

npm install -g @revenium/cli

Getting Started

Configuration

Create a .env file in your project root. See .env.example for all available options.

Minimum required:

REVENIUM_API_KEY=rev_mk_your_revenium_api_key_here
REVENIUM_ENDPOINT=https://api.revenium.ai

Quick Start - Claude Code

revenium-metering setup

The setup wizard will prompt for your API key, email, subscription tier, and endpoint. It automatically:

1. Validates your API key format (hak_ or rev_ prefix)
2. Tests connectivity to the Revenium endpoint
3. Writes configuration to ~/.claude/revenium.env
4. Updates your shell profile with the required environment variables

After setup, verify with:

revenium-metering status    # Check configuration and connectivity
revenium-metering test      # Send a test metric to verify integration

Quick Start - Gemini CLI

revenium-gemini setup

Generates both bash and fish shell configurations. Writes to ~/.gemini/revenium.env.

revenium-gemini status
revenium-gemini test

Quick Start - Cursor IDE

revenium-cursor setup

Requires both a Cursor Admin API key and a Revenium API key. Tests connectivity to both APIs during setup.

revenium-cursor status              # Check config, sync state, connectivity
revenium-cursor sync                # One-time sync of usage events
revenium-cursor sync --watch        # Continuous sync (default: every 5 min)
revenium-cursor test                # Send test metric

Quick Start - GitHub Copilot

revenium-copilot setup

Requires a GitHub personal access token with manage_billing:copilot or read:org scope and a Revenium API key. Syncs organization-level Copilot usage metrics.

revenium-copilot status              # Check config, sync state, connectivity
revenium-copilot sync                # One-time sync of usage events
revenium-copilot sync --watch        # Continuous sync (default: every 5 min)
revenium-copilot test                # Send test metric

Quick Start - Codex CLI

revenium-codex setup

Writes OTLP configuration to the [otel] section of ~/.codex/config.toml. Codex CLI natively exports telemetry using this config.

revenium-codex status                # Check otel config and connectivity
revenium-codex test                  # Send test metric
revenium-codex backfill --since 7d   # Import historical sessions

Command Reference

Claude Code (revenium-metering)

setup

Interactive setup wizard for Claude Code metering.

| Option | Description | |--------|-------------| | --api-key <key> | Revenium API key (skips prompt) | | --email <email> | Email for usage attribution | | --tier <tier> | Subscription tier: pro, max_5x, max_20x, team_premium, enterprise, api | | --endpoint <url> | Revenium API endpoint (default: https://api.revenium.ai) | | --organization <name> | Organization name | | --product <name> | Product name | | --skip-shell-update | Skip shell profile modification |

status

Displays current configuration (masked credentials), environment variable load status, and endpoint health with latency.

test

Sends a test OTLP metric and displays the response.

| Option | Description | |--------|-------------| | --verbose | Show full request/response details |

backfill

Imports historical usage data from Claude Code JSONL files (~/.claude/projects/).

| Option | Description | |--------|-------------| | --since <date> | Import since date (ISO format or relative: 7d, 1m, 3m) | | --dry-run | Preview records without sending | | --batch-size <n> | Records per batch, max 100 (default: 10) | | --delay <ms> | Minimum delay between batches in ms (default: 0) | | --verbose | Show per-record details |

Gemini CLI (revenium-gemini)

setup

Interactive setup wizard for Gemini CLI metering. Generates both bash and fish shell configurations.

| Option | Description | |--------|-------------| | --api-key <key> | Revenium API key | | --email <email> | Email for usage attribution | | --organization <name> | Organization name | | --product <name> | Product name | | --cost-multiplier <n> | Cost multiplier for pricing adjustments (default: 1.0) | | --endpoint <url> | Revenium API endpoint | | --skip-shell-update | Skip shell profile modification |

status

Displays configuration, shell environment status, and endpoint health.

test

Sends a test OTLP metric.

| Option | Description | |--------|-------------| | --verbose | Show full request/response details |

Cursor IDE (revenium-cursor)

setup

Interactive setup wizard requiring both Cursor Admin API and Revenium API keys.

| Option | Description | |--------|-------------| | --cursor-api-key <key> | Cursor admin API key | | --api-key <key> | Revenium API key | | --email <email> | Email for usage attribution | | --organization <name> | Organization name | | --product <name> | Product name | | --endpoint <url> | Revenium API endpoint | | --subscription-tier <tier> | Cursor tier: pro, business, enterprise, api | | --sync-interval <min> | Sync interval in minutes (default: 5) |

status

Displays configuration, sync state (last sync time, event count), and connectivity to both Cursor and Revenium APIs.

test

Sends a test OTLP metric.

| Option | Description | |--------|-------------| | --verbose | Show full request/response details |

sync

Syncs Cursor usage events to Revenium.

| Option | Description | |--------|-------------| | --watch | Run continuously with periodic sync | | --from <date> | Sync from date (ISO format) | | --to <date> | Sync to date (ISO format) |

reset

Clears sync state for a fresh sync. Displays current state before resetting.

backfill

Imports historical Cursor usage data.

| Option | Description | |--------|-------------| | --since <date> | Import since date | | --to <date> | Import until date | | --dry-run | Preview without sending | | --batch-size <n> | Records per batch, max 100 (default: 10) | | --delay <ms> | Minimum delay between batches in ms (default: 0) | | --verbose | Show per-record details |

GitHub Copilot (revenium-copilot)

setup

Interactive setup wizard for GitHub Copilot metering. Requires a GitHub token and organization slug.

| Option | Description | |--------|-------------| | --github-token <token> | GitHub personal access token | | --github-org <org> | GitHub organization slug | | --api-key <key> | Revenium API key | | --email <email> | Email for usage attribution | | --organization <name> | Organization name | | --product <name> | Product name | | --endpoint <url> | Revenium API endpoint | | --subscription-tier <tier> | Copilot tier: individual, business, enterprise | | --sync-interval <min> | Sync interval in minutes (default: 5) |

status

Displays configuration, sync state, and connectivity to both GitHub and Revenium APIs.

test

Sends a test OTLP metric.

| Option | Description | |--------|-------------| | --verbose | Show full request/response details |

sync

Syncs GitHub Copilot organization usage events to Revenium.

| Option | Description | |--------|-------------| | --watch | Run continuously with configured interval | | --from <date> | Start date for sync range (YYYY-MM-DD) | | --to <date> | End date for sync range (YYYY-MM-DD) | | --dry-run | Output OTLP JSON without sending data |

reset

Clears sync state for a fresh sync.

backfill

Imports historical GitHub Copilot usage data (max 28 days via GitHub API).

| Option | Description | |--------|-------------| | --since <date> | Start date (ISO 8601 or relative: 7d, 1m) | | --to <date> | End date (ISO 8601, defaults to now) | | --dry-run | Preview without sending | | --batch-size <n> | Events per batch, max 100 (default: 10) | | --delay <ms> | Minimum delay between batches in ms (default: 0) | | --verbose | Show detailed output |

OpenAI Codex CLI (revenium-codex)

setup

Interactive setup wizard for Codex CLI metering. Writes OTLP config to ~/.codex/config.toml.

| Option | Description | |--------|-------------| | --api-key <key> | Revenium API key | | --email <email> | Email for usage attribution | | --organization <name> | Organization name | | --product <name> | Product name | | --endpoint <url> | Revenium API endpoint | | --config-path <path> | Path to Codex config.toml (default: ~/.codex/config.toml) | | --skip-shell-update | Skip shell profile modification | | --force | Overwrite existing [otel] config without prompting |

status

Displays Codex OTLP configuration and endpoint health.

| Option | Description | |--------|-------------| | --config-path <path> | Path to Codex config.toml |

test

Sends a test OTLP metric.

| Option | Description | |--------|-------------| | --verbose | Show full request/response details | | --config-path <path> | Path to Codex config.toml |

backfill

Imports historical Codex usage sessions from ~/.codex/sessions/.

| Option | Description | |--------|-------------| | --since <date> | Start date (ISO or relative: 7d, 1m) | | --to <date> | End date (ISO format, defaults to now) | | --dry-run | Preview without sending | | --batch-size <n> | Records per batch | | --verbose | Show detailed output | | --sessions-path <path> | Path to Codex sessions root | | --config-path <path> | Path to Codex config.toml |

Subscription Tiers

Claude Code

| Tier | Plan | Cost Multiplier | |------|------|-----------------| | pro | Pro (~$20/mo) | 0.16 | | max_5x | Max 5x (~$100/mo) | 0.16 | | max_20x | Max 20x (~$200/mo) | 0.08 | | team_premium | Team Premium (~$125/seat) | 0.20 | | enterprise | Enterprise (custom) | 0.05 | | api | API (no subscription) | 1.00 |

Cursor

| Tier | Plan | Cost Multiplier | |------|------|-----------------| | pro | Pro ($20/mo) | 0.04 | | business | Business ($40/seat/mo) | 0.08 | | enterprise | Enterprise (custom) | 0.05 | | api | API / Pay-as-you-go | 1.00 |

GitHub Copilot

| Tier | Plan | Price | |------|------|-------| | individual | Individual | $10/month | | business | Business | $19/user/month | | enterprise | Enterprise | $39/user/month |

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | REVENIUM_API_KEY | Yes | Revenium API key (starts with hak_ or rev_) | | REVENIUM_ENDPOINT | No | API endpoint (default: https://api.revenium.ai) | | REVENIUM_EMAIL | No | Email for usage attribution | | REVENIUM_ORGANIZATION_NAME | No | Organization name for cost attribution | | REVENIUM_PRODUCT_NAME | No | Product name for cost attribution | | REVENIUM_COST_MULTIPLIER | No | Cost multiplier override (default: 1.0) |

Cursor-Specific Variables

| Variable | Required | Description | |----------|----------|-------------| | CURSOR_API_KEY | Yes (Cursor) | Cursor admin API key | | CURSOR_SUBSCRIPTION_TIER | No | Subscription tier: pro, business, enterprise, api | | REVENIUM_SYNC_INTERVAL_MS | No | Sync interval in milliseconds (default: 300000) |

Copilot-Specific Variables

| Variable | Required | Description | |----------|----------|-------------| | GITHUB_TOKEN | Yes (Copilot) | GitHub personal access token | | GITHUB_ORG | Yes (Copilot) | GitHub organization slug | | COPILOT_SUBSCRIPTION_TIER | No | Subscription tier: individual, business, enterprise | | REVENIUM_SYNC_INTERVAL_MS | No | Sync interval in milliseconds (default: 300000) |

Configuration File Locations

| Tool | Config Path | Permissions | |------|-------------|-------------| | Claude Code | ~/.claude/revenium.env | 0o600 (owner read/write) | | Gemini CLI | ~/.gemini/revenium.env | 0o600 (owner read/write) | | Cursor IDE | ~/.cursor/revenium/revenium.env | 0o600 (owner read/write) | | Cursor State | ~/.cursor/revenium/state.json | 0o600 (owner read/write) | | GitHub Copilot | ~/.github-copilot/revenium/revenium.env | 0o600 (owner read/write) | | Copilot State | ~/.github-copilot/revenium/state.json | 0o600 (owner read/write) | | Codex CLI | ~/.codex/config.toml ([otel] section) | — |

See .env.example for the complete list with all optional configuration.

Programmatic API

The package exports utility functions and types for programmatic use:

import {
  validateApiKey,
  validateEmail,
  validateEndpointUrl,
  sendOtlpLogs,
  checkEndpointHealth,
  createTestPayload,
  generateTestSessionId,
  maskApiKey,
  maskEmail,
  detectShell,
  getProfilePath,
} from '@revenium/cli';

Validation

| Function | Description | |----------|-------------| | validateApiKey(key) | Validate Revenium API key format (hak_ or rev_ prefix, min length) | | validateEmail(email) | Validate email address format (RFC-compliant) | | validateEndpointUrl(url) | Validate endpoint URL format and protocol |

OTLP Client

| Function | Description | |----------|-------------| | sendOtlpLogs(payload, endpoint, apiKey) | Send OTLP log payload with retry (3 attempts, exponential backoff) |

Health Check

| Function | Description | |----------|-------------| | checkEndpointHealth(endpoint, apiKey) | Test Revenium endpoint connectivity (returns latency) | | createTestPayload() | Create a test OTLP payload with metadata | | generateTestSessionId() | Generate a unique test session ID |

Shell Utilities

| Function | Description | |----------|-------------| | detectShell() | Detect current shell type (bash, zsh, fish, unknown) | | getProfilePath(shell) | Get shell profile file path for the detected shell | | maskApiKey(key) | Mask API key for safe display (first 4 + last 4 chars) | | maskEmail(email) | Mask email for safe display (first char + domain) |

Type Exports

import type {
  ReveniumCliConfig,
  ValidationResult,
  HealthCheckResult,
  ShellType,
  ShellUpdateResult,
  OTLPValue,
  OTLPLogsPayload,
  OTLPResponse,
  ToolContext,
  ToolMetadata,
  ToolEventPayload,
  ToolCallReport,
} from '@revenium/cli';

Troubleshooting

Setup wizard fails

1. Verify your API key starts with hak_ or rev_
2. Check internet connectivity to https://api.revenium.ai
3. Run status command to verify existing configuration
4. Try passing options directly: revenium-metering setup --api-key rev_mk_...

Shell profile not updated

1. Check that your shell profile file is writable
2. Verify detected shell: run revenium-metering status to see detected shell type
3. Use --skip-shell-update and configure manually by adding source ~/.claude/revenium.env to your profile
4. A backup of your profile is created before any modification (~/.zshrc.revenium-backup-<timestamp>)

Cursor sync not working

1. Verify CURSOR_API_KEY is a valid Cursor Admin API key
2. Run revenium-cursor status to check connectivity to both APIs
3. Try revenium-cursor reset to clear sync state and start fresh
4. Check for lock file: ~/.cursor/revenium/revenium-cursor.lock
5. Use revenium-cursor sync --watch for continuous sync with automatic retry

Copilot sync not working

1. Verify GITHUB_TOKEN has manage_billing:copilot or read:org scope
2. Verify GITHUB_ORG matches your GitHub organization slug
3. Run revenium-copilot status to check connectivity to both APIs
4. Try revenium-copilot reset to clear sync state and start fresh
5. Check for lock file: ~/.github-copilot/revenium/revenium-copilot.lock
6. GitHub Copilot API returns max 28 days of usage data per request

Test metric shows 0 processed events

This is expected for test metrics. The endpoint acknowledges receipt but processes test events differently from production data.

Debug

Contact [email protected] with:

• CLI tool name and version (revenium-metering --version)
• Output of status command
• Operating system and shell type
• Node.js version (node --version)

Testing

npm test                 # Run all tests
npm run test:core        # Run core module tests
npm run test:cursor      # Run Cursor-specific tests
npm run test:integration # Run CLI binary integration tests
npm run test:coverage    # Run tests with V8 coverage report
npm run test:watch       # Run tests in watch mode

E2E Integration Tests

E2E tests validate the full CLI flow for each provider against the live Revenium API. They run daily at 9:00 AM EST via GitHub Actions and can also be triggered manually.

export REVENIUM_E2E_API_KEY=hak_your_key_here
npm run build && npm run test:e2e

See TESTING.md for the full testing guide: architecture, environment variables, provider configurations, CI/CD workflows, and test helpers.

npm run lint             # ESLint check
npm run lint:fix         # ESLint auto-fix
npm run format           # Prettier format
npm run format:check     # Prettier check

Requirements

• Node.js 20+

Contributing

See CONTRIBUTING.md

Code of Conduct

See CODE_OF_CONDUCT.md

Security

See SECURITY.md

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Website: www.revenium.ai
• Documentation: docs.revenium.io
• Issues: Report bugs or request features
• Email: [email protected]

Built by Revenium