CLI Tool

Install and use the @offerhub/cli to manage API keys, inspect configuration, and understand CLI capabilities and API availability.

The @offerhub/cli package provides a command-line interface for managing the OFFER-HUB Orchestrator. It offers rapid configuration inspection and API key creation from the terminal without writing raw curl commands.

Tip

For developers integrating marketplaces, the CLI is the fastest way to generate initial API keys after bootstrapping your Orchestrator instance. Install it, run offerhub keys create, and you have a usable API key in seconds.

Installation

bash

# Global installation
npm install -g @offerhub/cli

# Or run directly via npx (no install required)
npx @offerhub/cli

The CLI registers a single binary: offerhub.

Configuration

The CLI resolves its connection settings from three sources, evaluated in strict priority order (packages/cli/src/utils/config.ts:loadConfig):

Priority	Source	Details
1	Environment variables	`OFFERHUB_API_URL` and `OFFERHUB_API_KEY` in the current shell environment
2	`.env` file	`.env` file in the current working directory (loaded via `dotenv`)
3	Global config file	`~/.offerhub/config.json`

Setting Environment Variables

bash

export OFFERHUB_API_URL=http://localhost:4000
export OFFERHUB_API_KEY=ohk_live_your_api_key

Global Configuration (`~/.offerhub/config.json`)

You can save default connection settings to ~/.offerhub/config.json so you do not need to export environment variables in every shell session.

json

{
  "apiUrl": "http://localhost:4000",
  "apiKey": "ohk_master_your_master_or_admin_key",
  "paymentProvider": "crypto"
}

Commands

Config Commands

`offerhub config set`

Configure connection settings interactively or non-interactively via flags.

bash

# Interactive setup (prompts for API URL, API key, and payment provider)
offerhub config set

# Non-interactive setup via flags
offerhub config set --api-url http://localhost:4000 --api-key ohk_master_xxx

Option	Type	Description
`--api-url <url>`	String	Orchestrator API base URL (default: `http://localhost:3000` interactively)
`--api-key <key>`	String	Master key or administrative API key

When run interactively in crypto mode, the wizard also generates and displays a random 32-byte hex WALLET_ENCRYPTION_KEY suitable for your Orchestrator .env.

`offerhub config show`

Displays the active configuration (API URL, masked key, payment provider, and file path of ~/.offerhub/config.json).

offerhub config show

Output:

typescript

Current Configuration:

API URL: http://localhost:4000
API Key: ohk_master...
Payment: crypto (default)

Config file: /Users/username/.offerhub/config.json

API Key Management

`offerhub keys list`

List all API keys stored in the Orchestrator database.

bash

# List all API keys
offerhub keys list

Option	Description	API Availability
`-u, --user-id <userId>`	Filter keys by user ID	Not supported in API. `AuthController.listApiKeys` (`apps/api/src/modules/auth/auth.controller.ts:36-47`) only accepts pagination parameters (`limit`, `cursor`). API keys are platform/tenant-level credentials rather than per-user keys. The `--user-id` flag is ignored by the backend.

Output:

typescript

┌──────────┬─────────────┬──────────┬───────────────┬────────────┬───────────┐
│ ID       │ Key         │ User ID  │ Scopes        │ Created    │ Last Used │
├──────────┼─────────────┼──────────┼───────────────┼────────────┼───────────┤
│ key_abc  │ ohk_***xyz  │ —        │ read, write   │ 1/1/2026   │ 1/5/2026  │
└──────────┴─────────────┴──────────┴───────────────┴────────────┴───────────┘

`offerhub keys create`

Create a new API key. Runs interactively if flags are omitted.

bash

# Interactive — prompts for scopes and key name
offerhub keys create

# Non-interactive
offerhub keys create \
  --scopes read,write \
  --name "Production Marketplace Key"

Option	Description	API Availability
`-s, --scopes <scopes>`	Comma-separated scopes: `read`, `write`, `support` (or domain scopes: `orders`, `users`, `balance`)	Supported. Validated by `ScopeGuard` on the Orchestrator API (`apps/api/src/modules/auth/auth.controller.ts:27`).
`-n, --name <name>`	Key name or descriptive label	Supported. Persisted in the `ApiKey` database model.
`-u, --user-id <userId>`	User ID prompt / flag	Not supported in API. The backend endpoint `POST /auth/api-keys` binds only `name` and `scopes`. API keys belong to the marketplace integration, not to individual end users.

Danger

The plaintext API key (ohk_...) is returned only once at creation time. The Orchestrator stores a cryptographic hash (bcrypt) with salt in the database. Copy the key immediately — it cannot be recovered later.

`offerhub keys revoke <keyId>` Unavailable in API

The CLI provides a revoke command to revoke an API key by ID:

bash

offerhub keys revoke key_abc123 --yes

Warning

Backend route not implemented: offerhub keys revoke sends DELETE /auth/api-keys/:id (packages/cli/src/commands/keys.ts:179). However, DELETE /auth/api-keys/:id does not currently exist in the Orchestrator API (apps/api/src/modules/auth/auth.controller.ts). Running this command returns an HTTP 404 error.

To revoke an API key in current releases, delete or deactivate the corresponding row directly in the PostgreSQL ApiKey table or rotate credentials.

`offerhub keys token <keyId>`

Generate a short-lived token (ohk_tok_...) from an existing API key for temporary frontend or delegate sessions (POST /auth/api-keys/:id/token).

bash

# Generate short-lived token
offerhub keys token key_abc123

Option	Description	Behavior
`-t, --ttl <seconds>`	Requested token TTL in seconds	Fixed at 1 hour (3600s). The Orchestrator backend (`apps/api/src/modules/auth/auth.service.ts:58-60`) hardcodes token expiration to `expiresIn: '1h'`. The `--ttl` flag has no effect on server-side token lifetime.

Output:

typescript

✓ Token generated successfully!

Token: ohk_tok_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Expires: 1/5/2026, 2:00:00 PM

⚠️  This token will expire in 1 hour. Save it now!

Maintenance Commands Unavailable in API

The CLI exposes three commands intended for managing Orchestrator maintenance mode:

offerhub maintenance enable
offerhub maintenance disable
offerhub maintenance status

Warning

Backend routes not implemented: These commands dispatch requests to admin/maintenance/enable, admin/maintenance/disable, and admin/maintenance/status (packages/cli/src/commands/maintenance.ts). However, no maintenance controller or routes exist in the Orchestrator API (apps/api/src/modules). Executing any maintenance command will fail with an HTTP 404 route error.

Common Workflows

1. Create Your First API Key (Fastest Path)

After provisioning the Orchestrator using the Scaffolder, configure the CLI and create an API key:

bash

# 1. Point the CLI to your local Orchestrator using the master key from setup
offerhub config set --api-url http://localhost:4000 --api-key YOUR_OFFERHUB_MASTER_KEY

# 2. Create an administrative API key
offerhub keys create --name "Development Key" --scopes read,write,support

2. Generate a Client Session Token

To authenticate client requests without exposing the long-lived master or production API key, generate a short-lived 1-hour session token:

bash

offerhub keys token key_abc123

Use the returned ohk_tok_... token in the Authorization: Bearer ohk_tok_... header for client requests.

Error Handling

If configuration is missing when running any command, the CLI provides clear instructions:

typescript

❌ Error: No configuration found.

Please configure the CLI using one of these methods:

1. Environment variables:
   export OFFERHUB_API_URL=https://api.offerhub.com
   export OFFERHUB_API_KEY=ohk_your_api_key

2. .env file in current directory:
   OFFERHUB_API_URL=https://api.offerhub.com
   OFFERHUB_API_KEY=ohk_your_api_key

3. Run: offerhub config set

Next Steps

Scaffolder Guide — One-command interactive setup wizard (create-offer-hub-orchestrator)
Quick Start — Make your first authenticated payment and escrow call
Installation Guide — Complete setup instructions
Configuration Reference — All Orchestrator environment variables
API Reference — Full REST API documentation

Edit this page on GitHub

CLI Tool

Install and use the @offerhub/cli to manage API keys, inspect configuration, and understand CLI capabilities and API availability.

Tip

Installation

bash

# Global installation
npm install -g @offerhub/cli

# Or run directly via npx (no install required)
npx @offerhub/cli

The CLI registers a single binary: offerhub.

Configuration

The CLI resolves its connection settings from three sources, evaluated in strict priority order (packages/cli/src/utils/config.ts:loadConfig):

Priority	Source	Details
1	Environment variables	`OFFERHUB_API_URL` and `OFFERHUB_API_KEY` in the current shell environment
2	`.env` file	`.env` file in the current working directory (loaded via `dotenv`)
3	Global config file	`~/.offerhub/config.json`

Setting Environment Variables

bash

export OFFERHUB_API_URL=http://localhost:4000
export OFFERHUB_API_KEY=ohk_live_your_api_key

Global Configuration (`~/.offerhub/config.json`)

You can save default connection settings to ~/.offerhub/config.json so you do not need to export environment variables in every shell session.

json

{
  "apiUrl": "http://localhost:4000",
  "apiKey": "ohk_master_your_master_or_admin_key",
  "paymentProvider": "crypto"
}

Commands

Config Commands

`offerhub config set`

Configure connection settings interactively or non-interactively via flags.

bash

# Interactive setup (prompts for API URL, API key, and payment provider)
offerhub config set

# Non-interactive setup via flags
offerhub config set --api-url http://localhost:4000 --api-key ohk_master_xxx

Option	Type	Description
`--api-url <url>`	String	Orchestrator API base URL (default: `http://localhost:3000` interactively)
`--api-key <key>`	String	Master key or administrative API key

When run interactively in crypto mode, the wizard also generates and displays a random 32-byte hex WALLET_ENCRYPTION_KEY suitable for your Orchestrator .env.

`offerhub config show`

Displays the active configuration (API URL, masked key, payment provider, and file path of ~/.offerhub/config.json).

offerhub config show

Output:

typescript

Current Configuration:

API URL: http://localhost:4000
API Key: ohk_master...
Payment: crypto (default)

Config file: /Users/username/.offerhub/config.json

API Key Management

`offerhub keys list`

List all API keys stored in the Orchestrator database.

bash

# List all API keys
offerhub keys list

Option	Description	API Availability
`-u, --user-id <userId>`	Filter keys by user ID	Not supported in API. `AuthController.listApiKeys` (`apps/api/src/modules/auth/auth.controller.ts:36-47`) only accepts pagination parameters (`limit`, `cursor`). API keys are platform/tenant-level credentials rather than per-user keys. The `--user-id` flag is ignored by the backend.

Output:

typescript

┌──────────┬─────────────┬──────────┬───────────────┬────────────┬───────────┐
│ ID       │ Key         │ User ID  │ Scopes        │ Created    │ Last Used │
├──────────┼─────────────┼──────────┼───────────────┼────────────┼───────────┤
│ key_abc  │ ohk_***xyz  │ —        │ read, write   │ 1/1/2026   │ 1/5/2026  │
└──────────┴─────────────┴──────────┴───────────────┴────────────┴───────────┘

`offerhub keys create`

Create a new API key. Runs interactively if flags are omitted.

bash

# Interactive — prompts for scopes and key name
offerhub keys create

# Non-interactive
offerhub keys create \
  --scopes read,write \
  --name "Production Marketplace Key"

Option	Description	API Availability
`-s, --scopes <scopes>`	Comma-separated scopes: `read`, `write`, `support` (or domain scopes: `orders`, `users`, `balance`)	Supported. Validated by `ScopeGuard` on the Orchestrator API (`apps/api/src/modules/auth/auth.controller.ts:27`).
`-n, --name <name>`	Key name or descriptive label	Supported. Persisted in the `ApiKey` database model.
`-u, --user-id <userId>`	User ID prompt / flag	Not supported in API. The backend endpoint `POST /auth/api-keys` binds only `name` and `scopes`. API keys belong to the marketplace integration, not to individual end users.

Danger

`offerhub keys revoke <keyId>` Unavailable in API

The CLI provides a revoke command to revoke an API key by ID:

bash

offerhub keys revoke key_abc123 --yes

Warning

To revoke an API key in current releases, delete or deactivate the corresponding row directly in the PostgreSQL ApiKey table or rotate credentials.

`offerhub keys token <keyId>`

Generate a short-lived token (ohk_tok_...) from an existing API key for temporary frontend or delegate sessions (POST /auth/api-keys/:id/token).

bash

# Generate short-lived token
offerhub keys token key_abc123

Option	Description	Behavior
`-t, --ttl <seconds>`	Requested token TTL in seconds	Fixed at 1 hour (3600s). The Orchestrator backend (`apps/api/src/modules/auth/auth.service.ts:58-60`) hardcodes token expiration to `expiresIn: '1h'`. The `--ttl` flag has no effect on server-side token lifetime.

Output:

typescript

✓ Token generated successfully!

Token: ohk_tok_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Expires: 1/5/2026, 2:00:00 PM

⚠️  This token will expire in 1 hour. Save it now!

Maintenance Commands Unavailable in API

The CLI exposes three commands intended for managing Orchestrator maintenance mode:

offerhub maintenance enable
offerhub maintenance disable
offerhub maintenance status

Warning

Common Workflows

1. Create Your First API Key (Fastest Path)

After provisioning the Orchestrator using the Scaffolder, configure the CLI and create an API key:

bash

# 1. Point the CLI to your local Orchestrator using the master key from setup
offerhub config set --api-url http://localhost:4000 --api-key YOUR_OFFERHUB_MASTER_KEY

# 2. Create an administrative API key
offerhub keys create --name "Development Key" --scopes read,write,support

2. Generate a Client Session Token

To authenticate client requests without exposing the long-lived master or production API key, generate a short-lived 1-hour session token:

bash

offerhub keys token key_abc123

Use the returned ohk_tok_... token in the Authorization: Bearer ohk_tok_... header for client requests.

Error Handling

If configuration is missing when running any command, the CLI provides clear instructions:

typescript

❌ Error: No configuration found.

Please configure the CLI using one of these methods:

1. Environment variables:
   export OFFERHUB_API_URL=https://api.offerhub.com
   export OFFERHUB_API_KEY=ohk_your_api_key

2. .env file in current directory:
   OFFERHUB_API_URL=https://api.offerhub.com
   OFFERHUB_API_KEY=ohk_your_api_key

3. Run: offerhub config set

Next Steps

Scaffolder Guide — One-command interactive setup wizard (create-offer-hub-orchestrator)
Quick Start — Make your first authenticated payment and escrow call
Installation Guide — Complete setup instructions
Configuration Reference — All Orchestrator environment variables
API Reference — Full REST API documentation

Edit this page on GitHub

CLI Tool

Installation

Configuration

Setting Environment Variables

Global Configuration (~/.offerhub/config.json)

Commands

Config Commands

offerhub config set

offerhub config show

API Key Management

offerhub keys list

offerhub keys create

offerhub keys revoke <keyId> Unavailable in API

offerhub keys token <keyId>

Maintenance Commands Unavailable in API

Common Workflows

1. Create Your First API Key (Fastest Path)

2. Generate a Client Session Token

Error Handling

Next Steps

CLI Tool

Installation

Configuration

Setting Environment Variables

Global Configuration (~/.offerhub/config.json)

Commands

Config Commands

offerhub config set

offerhub config show

API Key Management

offerhub keys list

offerhub keys create

offerhub keys revoke <keyId> Unavailable in API

offerhub keys token <keyId>

Maintenance Commands Unavailable in API

Common Workflows

1. Create Your First API Key (Fastest Path)

2. Generate a Client Session Token

Error Handling

Next Steps

Global Configuration (`~/.offerhub/config.json`)

`offerhub config set`

`offerhub config show`

`offerhub keys list`

`offerhub keys create`

`offerhub keys revoke <keyId>` Unavailable in API

`offerhub keys token <keyId>`

Global Configuration (`~/.offerhub/config.json`)

`offerhub config set`

`offerhub config show`

`offerhub keys list`

`offerhub keys create`

`offerhub keys revoke <keyId>` Unavailable in API

`offerhub keys token <keyId>`