CBCLI User Guide

cbcli is a unified command-line interface for Nominate AI services, following AWS CLI patterns.

cbcli <service> <resource> <command> [options]

---

Table of Contents

1. Installation
2. Quick Start
3. Core Concepts
4. Service Types
5. Command Structure
6. Commands Reference
7. services
8. spec
9. describe
10. exec
11. auth
12. cache
13. Service Shorthand Commands
14. Available Services
15. Platform Services
16. Tenant Services
17. Authentication
18. API Key Authentication
19. Username/Password Authentication
20. Token Management
21. Working with Tenant Services
22. Output Formats
23. Configuration
24. Troubleshooting

---

Installation

# Clone the repository
git clone <repository-url>
cd cbcli

# Install in development mode
pip install -e .

# Verify installation
cbcli --version

---

Quick Start

# List all available services
cbcli services

# Show what resources are available in a service
cbcli intel

# Describe a specific resource
cbcli describe intel jobs

# Execute an API command
cbcli intel jobs list

# For tenant services, specify the tenant
cbcli app --tenant mi20 auth me

---

Core Concepts

Service Types

cbcli supports two types of services:

Type	Description	URL Pattern	Example
platform	Direct access services	https://{service}.nominate.ai	cbcli intel jobs list
tenant	Tenant-specific services	https://{tenant}.nominate.ai	cbcli app --tenant mi20 auth me

Command Structure

cbcli [global-options] <command> [command-options] [arguments]

Global Options: - --version, -v - Show version - --debug - Enable debug logging - --help - Show help message

---

Commands Reference

services - List Available Services

List all registered services with their types and URLs.

# List all services
cbcli services

# Filter by service type
cbcli services --type platform
cbcli services --type tenant

Example Output:

┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ service  ┃ name             ┃ type     ┃ url                          ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ intel    │ Intelligence API │ platform │ https://intel.nominate.ai    │
│ app      │ CampaignBrain    │ tenant   │ https://{tenant}.nominate.ai │
└──────────┴──────────────────┴──────────┴──────────────────────────────┘

---

spec - Show Service Resources

Display available resources and commands for a service.

cbcli spec <service> [options]

Options: - --tenant, -T - Tenant slug (required for tenant services) - --refresh, -r - Force refresh from server - --raw - Show raw OpenAPI JSON spec

Examples:

# Show resources for intel service
cbcli spec intel

# Show resources for a tenant service
cbcli spec app --tenant mi20

# Force refresh the cached spec
cbcli spec intel --refresh

# Get raw OpenAPI JSON
cbcli spec intel --raw

Shorthand: You can also use the service name directly:

cbcli intel          # Same as: cbcli spec intel
cbcli app -T mi20    # Same as: cbcli spec app --tenant mi20

---

describe - Describe a Resource

Get detailed information about a resource and its available commands.

cbcli describe <service> <resource> [options]

Options: - --tenant, -T - Tenant slug (for tenant services) - --command, -c - Describe a specific command

Examples:

# List all commands for a resource
cbcli describe intel jobs

# Describe a specific command with parameters
cbcli describe intel jobs --command create

# Describe tenant service resource
cbcli describe app --tenant mi20 events

# Get details on a specific command
cbcli describe app --tenant mi20 events --command create

Example Output:

intel jobs

  list - GET /api/v1/jobs
    List all jobs
  create - POST /api/v1/jobs
    Create a new job
  get - GET /api/v1/jobs/{job_id}
    Get job by ID
  delete - DELETE /api/v1/jobs/{job_id}
    Delete a job
  cancel - POST /api/v1/jobs/{job_id}/cancel
    Cancel a running job

---

exec - Execute API Commands

Execute an API command with parameters.

cbcli exec <service> <resource> <command> [options]

Options: - --tenant, -T - Tenant slug (for tenant services) - --params, -p - JSON parameters for the request - --output, -o - Output format: json (default) or table

Examples:

# Simple GET request
cbcli exec intel jobs list

# GET with query parameters
cbcli exec intel jobs list --params '{"status": "running", "limit": 10}'

# POST with body parameters
cbcli exec intel jobs create --params '{"name": "my-job", "graph_name": "crawl"}'

# With path parameters
cbcli exec intel jobs get --params '{"job_id": "abc123"}'

# Tenant service
cbcli exec app --tenant mi20 events list

# Table output
cbcli exec intel jobs list --output table

Shorthand: Use service commands directly:

cbcli intel jobs list                    # Same as: cbcli exec intel jobs list
cbcli intel jobs create -p '{"name":"x"}'  # Same as: cbcli exec intel jobs create --params '...'

---

auth - Authentication Management

Manage authentication tokens for services.

auth login - Login to a Service

cbcli auth login <service> [options]

Options: - --tenant, -T - Tenant slug (for tenant services) - --username, -u - Username for OAuth2 login - --password - Password for OAuth2 login - --token - Direct API key/token input

Examples:

# Login with API key (platform services)
cbcli auth login intel --token "your-api-key-here"

# Login with username/password (tenant services)
cbcli auth login app --tenant mi20 --username admin --password secret

# Interactive login (prompts for credentials)
cbcli auth login app --tenant mi20

# Login to tenant management
cbcli auth login tenant --username admin --password secret

auth logout - Remove Stored Token

cbcli auth logout <service> [options]

Examples:

# Logout from platform service
cbcli auth logout intel

# Logout from tenant service
cbcli auth logout app --tenant mi20

auth list - List Stored Tokens

cbcli auth list

Example Output:

┏━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ service ┃ tenant   ┃ file                                   ┃
┡━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ intel   │          │ /home/user/.cbcli/tokens/intel.token   │
│ app     │ mi20     │ /home/user/.cbcli/tokens/app__mi20.token│
│ app     │ testsite │ /home/user/.cbcli/tokens/app__testsite.token│
└─────────┴──────────┴────────────────────────────────────────┘

auth status - Check Token Status

cbcli auth status <service> [options]

Examples:

# Check platform service token
cbcli auth status intel

# Check tenant service token
cbcli auth status app --tenant mi20

---

cache - Manage Spec Cache

Manage the local cache of OpenAPI specifications.

cbcli cache <action> [options]

Actions: - list - List cached specs (default) - clear - Clear cached specs - refresh - Clear cache to force refresh on next command

Options: - --service, -s - Target a specific service

Examples:

# List all cached specs
cbcli cache list

# Clear all cached specs
cbcli cache clear

# Clear cache for a specific service
cbcli cache clear --service intel

# Refresh (clear and fetch on next use)
cbcli cache refresh --service intel

Example Output:

┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ service ┃ url                        ┃ spec_hash    ┃ cached_at        ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ intel   │ https://intel.nominate.ai  │ a1b2c3d4e5f6 │ 2026-01-28 10:30 │
│ app:mi20│ https://mi20.nominate.ai   │ f6e5d4c3b2a1 │ 2026-01-28 11:15 │
└─────────┴────────────────────────────┴──────────────┴──────────────────┘

---

Service Shorthand Commands

Each service has a shorthand command for quick access:

# These are equivalent:
cbcli spec intel
cbcli intel

# These are equivalent:
cbcli describe intel jobs
cbcli intel jobs

# These are equivalent:
cbcli exec intel jobs list
cbcli intel jobs list

With tenant services:

# These are equivalent:
cbcli spec app --tenant mi20
cbcli app --tenant mi20

# These are equivalent:
cbcli exec app --tenant mi20 auth me
cbcli app --tenant mi20 auth me

---

Available Services

Platform Services

Service	Name	Description
intel	Intelligence API	Web crawling, screenshots, transcripts, job management
network	Network API	VPN cluster and geographic routing
ai	AI API	Chat, embeddings, summarization, OCR
index	Index API	Document indexing and semantic search
geo	Geocoding API	Forward and reverse geocoding
files	Files API	File storage and retrieval
auth	Auth Gateway	PIN-based authentication
districts	Districts API	Congressional district data
radio	Radio API	Political radio advertising rates
email	Email API	Headless IMAP/SMTP operations
sms	SMS API	SMS/MMS gateway via Ejoin devices
workflow	Workflow API	JSON-backed workflow engine
mobile	Mobile API	Mobile application backend
maps	Maps API	City map poster generation
tiles	Tiles API	CartoDB tile caching proxy
tor	TOR API	Anonymous routing via TOR cluster
models	Models API	DuckDB data analysis engine
unstructured	Unstructured API	Document parsing and extraction
mesh	Mesh API	Distributed WebSocket proxy network
surveys	Surveys API	Survey collection platform (YASP)
tenant	Tenant API	Tenant management and provisioning

Tenant Services

Service	Name	Description
app	CampaignBrain App	Campaign management application

---

Authentication

API Key Authentication

For platform services that use API keys:

# Store an API key
cbcli auth login intel --token "your-api-key-here"

# Verify it's stored
cbcli auth status intel

# Now use the service (token is automatically included)
cbcli intel jobs list

Username/Password Authentication

For services that use OAuth2 password flow:

# Login with credentials
cbcli auth login app --tenant mi20 --username myuser --password mypass

# Or interactively
cbcli auth login app --tenant mi20
# (prompts for username and password)

# Verify authentication
cbcli app --tenant mi20 auth me

Token Management

Tokens are stored in ~/.cbcli/tokens/ with restricted permissions (0600).

# See all stored tokens
cbcli auth list

# Check specific token
cbcli auth status intel

# Remove a token
cbcli auth logout intel
cbcli auth logout app --tenant mi20

---

Working with Tenant Services

Tenant services require the --tenant or -T flag:

# Login to a tenant
cbcli auth login app --tenant mi20 --username admin --password secret

# View available resources
cbcli app --tenant mi20

# Execute commands
cbcli app --tenant mi20 auth me
cbcli app --tenant mi20 events list
cbcli app --tenant mi20 communications create --params '{"subject": "Test"}'

Multiple Tenants:

# Login to multiple tenants
cbcli auth login app --tenant mi20 --username admin --password pass1
cbcli auth login app --tenant testsite --username admin --password pass2

# Switch between them with -T
cbcli app -T mi20 auth me
cbcli app -T testsite auth me

---

Output Formats

JSON Output (Default)

cbcli intel jobs list

{
  "jobs": [
    {"id": "job-1", "name": "Crawl Job", "status": "completed"},
    {"id": "job-2", "name": "Screenshot Job", "status": "running"}
  ]
}

Table Output

cbcli intel jobs list --output table

┏━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ id     ┃ name           ┃ status    ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ job-1  │ Crawl Job      │ completed │
│ job-2  │ Screenshot Job │ running   │
└────────┴────────────────┴───────────┘

---

Configuration

Directory Structure

~/.cbcli/
├── cache/           # Cached OpenAPI specs
│   ├── intel.json
│   └── app:mi20.json
├── tokens/          # Stored authentication tokens
│   ├── intel.token
│   └── app__mi20.token
└── services.yaml    # Custom service definitions (optional)

Custom Services

Add custom services via ~/.cbcli/services.yaml:

services:
  myapi:
    name: My Custom API
    url: https://api.example.com
    description: My custom API service
    type: platform
    spec_path: /openapi.json
    auth_header: X-API-Key

---

Troubleshooting

Debug Mode

Enable debug logging to see HTTP requests:

cbcli --debug intel jobs list

Common Issues

"Service requires --tenant parameter"

# Wrong:
cbcli app auth me

# Correct:
cbcli app --tenant mi20 auth me

"Could not validate credentials" (401)

# Re-authenticate
cbcli auth logout app --tenant mi20
cbcli auth login app --tenant mi20 --username user --password pass

"Resource not found"

# Check available resources
cbcli app --tenant mi20

# Use correct resource name from the list
cbcli app --tenant mi20 events list

Stale cache

# Clear and refresh
cbcli cache clear --service intel
cbcli intel  # Will fetch fresh spec

Getting Help

# General help
cbcli --help

# Command-specific help
cbcli auth --help
cbcli auth login --help
cbcli exec --help

---

Examples Cheat Sheet

# === Discovery ===
cbcli services                        # List all services
cbcli intel                           # Show intel resources
cbcli describe intel jobs             # Describe jobs resource
cbcli describe intel jobs -c create   # Describe create command

# === Authentication ===
cbcli auth login intel --token "key"  # API key login
cbcli auth login app -T mi20 -u admin # Password login
cbcli auth list                       # List tokens
cbcli auth status intel               # Check token
cbcli auth logout intel               # Remove token

# === API Calls ===
cbcli intel jobs list                 # List jobs
cbcli intel jobs list -o table        # Table output
cbcli intel jobs get -p '{"job_id":"123"}'  # With params
cbcli intel scheduler create -p '{"name":"daily","cron":"0 9 * * *"}'

# === Tenant Services ===
cbcli app -T mi20 auth me             # Current user
cbcli app -T mi20 events list         # List events
cbcli app -T mi20 communications create -p '{"subject":"Hello"}'

# === Cache ===
cbcli cache list                      # Show cached specs
cbcli cache clear                     # Clear all
cbcli cache clear -s intel            # Clear specific