cobalt-cli

The official command-line interface for the Cobalt Intelligence API.

Search Secretaries of State across all 50 states + DC, screen against OFAC and global sanctions lists, verify TINs, and run full 50-state business verifications — all from your terminal, in pipelines, or from AI agents.

# search a business
cobalt sos search "Acme Holdings" --state UT

# resume a long-running lookup
cobalt sos search "Slow State Co" --state CA --async   # returns retryId
cobalt sos retry <retryId>

# OFAC screen
cobalt ofac search "Some Person" --type person --score 95

# verify a TIN
cobalt tin verify --tin 123456789 --name "Acme Holdings LLC"

# fire a 50-state verification
cobalt full-verification start --business-name "Acme Holdings"
cobalt full-verification wait <searchGuid>

Why a CLI?

• AI-native: every command emits a JSON envelope on stdout — drop it into Claude, Cursor, OpenAI Codex, or any agent that can run shell commands and you have an instant business-data tool.
• Pipeable: cobalt sos search "Acme" --state UT | jq '.data.results[].sosId' | xargs -I{} cobalt sos get {} --state UT.
• Stable exit codes: scripts can branch on RATE_LIMITED (3) vs NOT_FOUND (2) vs UNAUTHORIZED (4) without parsing.
• Same surface as the API: every documented parameter is exposed as a flag.

Install

npm install -g @cobaltintelligence/cli
# or run on demand:
npx @cobaltintelligence/cli sos search "Acme" --state UT

Requires Node.js 18+.

Authentication

Get your API key from the Cobalt dashboard, then either:

cobalt auth login            # interactive prompt, stored under your OS user config
# or
export COBALT_API_KEY="***"   # env var wins; ideal for CI / agents
# or run the full guided flow (opens browser, prompts, saves, verifies):
cobalt auth setup

Verify:

cobalt auth status

For AI agents

This CLI is built for AI coding agents (Claude Code, Cursor, Cline, Codex, Aider). Two design choices make it easy:

1. Stable JSON envelopes. Every command emits { data, meta, error } with stable error codes and exit codes — agents can branch on error.code directly instead of parsing prose.
2. Human-action hints. When auth fails, the error envelope includes a structured error.details.onboarding object with signup_url, key_url, docs_url, and a human_action string the agent can read aloud to its human verbatim. No more hallucinated signup URLs.

Quick reference for an agent that hits a missing key:

# Print onboarding URLs + the human-action script (no error required):
cobalt auth urls --format json

Example response:

{
  "data": {
    "signup": "https://www.cobaltintelligence.com/sign-up",
    "keys": "https://www.cobaltintelligence.com/dashboard",
    "docs": "https://documentation.cobaltintelligence.com",
    "human_action": "You need a Cobalt Intelligence API key to use this tool. Ask your human to:\n  1. Sign up (free trial, no card): https://www.cobaltintelligence.com/sign-up\n  ..."
  }
}

What if my CLI crashes or times out mid-search?

Every Cobalt SOS search consumes a credit, even when the API has to fall back to a retryId (when a state's lookup takes longer than ~30s). To make sure you can always recover the result you paid for, the CLI:

1. Prints the retryId to stderr the moment it's issued — before any polling starts
2. Persists it to disk at ~/.config/cobalt-cli-nodejs/pending/<retryId>.json
3. Surfaces it on Ctrl+C with the exact command to recover
4. Includes retryId as a structured field in the TIMEOUT error envelope

If something goes wrong, recovery is one command:

cobalt sos pending             # see all outstanding retryIds
cobalt sos retry <retryId>     # fetch the result
cobalt sos pending clear <id>  # forget one (does not affect the server)

This means no Cobalt search you've paid for is ever unrecoverable — even if your laptop reboots mid-poll.

Concurrency guidance (for AI agents)

The Cobalt API itself accepts very high request rates, but the upstream Secretary-of-State scrapers have practical concurrency ceilings. Above the limits, requests are queued — not rejected — but latency grows fast. Keep your in-flight count at or below:

• 2 concurrent requests per state
• 5 concurrent requests per account (across all states)

A 429 response means the queue itself is saturated; honor retry_after_seconds. For long-running searches, prefer retryId polling over fanning out more parallel requests.

Read the limits at runtime (e.g. to size your worker pool):

cobalt limits --format json

The same rate_limits block is embedded inside cobalt auth status and inside every error.details.onboarding hint, so agents always see the guidance the first time they hit an auth wall.

Override the defaults locally (staging, custom tiers) with COBALT_MAX_CONCURRENT_PER_STATE and COBALT_MAX_CONCURRENT_PER_ACCOUNT.

Command reference

cobalt sos — Secretary of State

| Command | Description | |---|---| | cobalt sos search <query> --state <st> | Search by business name. Add --first-name/--last-name to search by person, or --sos-id for direct lookup. | | cobalt sos get <sosId> --state <st> | Direct entity-id fetch. | | cobalt sos retry <retryId> | Resume a previously-started long-running lookup. | | cobalt sos pending | List retryIds saved on disk that haven't completed yet. | | cobalt sos pending clear <retryId> | Forget a saved retryId (server-side state untouched). |

Useful flags: --cached (use cached not live), --screenshot, --ucc, --related, --street/--city/--zip (AND-filter), --test complete (dummy data, no charge), --callback-url, --async (don't poll, return retryId).

cobalt ofac — Sanctions screening

cobalt ofac search "Cuban Citrus Co" --type organization --sources SDN,NONSDN --score 95

cobalt tin — TIN verification

cobalt tin verify --tin 123456789 --name "Acme Holdings LLC"

cobalt full-verification (alias cobalt fv) — 50-state run

cobalt fv start --business-name "Acme Holdings" --callback-url https://example.com/hook
cobalt fv status <searchGuid>
cobalt fv wait <searchGuid>     # auto-poll until done

cobalt auth / cobalt config

cobalt auth login | logout | status
cobalt config get | set <k> <v> | unset <k> | path

Output format

Every command prints this envelope on stdout:

{
  "data": { ... },
  "meta": { "state": "UT" },
  "error": null
}

On error:

{
  "data": null,
  "meta": {},
  "error": {
    "code": "RATE_LIMITED",
    "message": "You have exceeded your rate limit.",
    "retry_after_seconds": 30
  }
}

When stdout is a TTY, the CLI pretty-prints data and sends meta to stderr. In pipelines (non-TTY) or with --format json, the full envelope is emitted as machine-readable JSON.

Exit codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | Unknown error | | 2 | Not found | | 3 | Rate limited (RATE_LIMITED) | | 4 | Auth problem (NO_API_KEY / UNAUTHORIZED) | | 5 | Bad request / validation | | 6 | Timeout | | 7 | Network error | | 8 | Cobalt server error (5xx) |

Global flags

-f, --format <json|pretty|table>   default: pretty in TTY, json in pipes
-q, --quiet                        suppress non-data output
-v, --verbose                      log each request to stderr
    --api-key <key>                override stored / env API key
    --endpoint <url>               override base URL (staging, local)
    --timeout <ms>                 request timeout, default 120000

AI-agent usage

The CLI is designed to be a first-class tool for autonomous coding agents and shell-using LLMs. Best practices:

1. Always call with --format json so output is parseable.
2. Use exit codes to branch — RATE_LIMITED and TIMEOUT are retryable; BAD_REQUEST and NOT_FOUND are not.
3. For long-running SOS lookups, use --async and store the retryId; resume with cobalt sos retry.
4. Store the API key in COBALT_API_KEY rather than in config files — easier to rotate and scope.

A companion MCP server (@cobaltintelligence/mcp-server) is on the roadmap. Until it ships, exposing this CLI as a tool to your agent is the recommended path.

Development

git clone https://github.com/cobalt-intelligence/cobalt-cli
cd cobalt-cli
npm install
npm run build
node dist/index.js --help

License

MIT © Cobalt Intelligence