HigherData CLI

Requires Node 24 or newer. Build from the repository root with npm run build, or build only this workspace with npm run build --workspace higherdata.

node packages/cli/dist/index.js --version
node packages/cli/dist/index.js --help

The package provides the higherdata command. After the first approved npm release, install with npm install --global higherdata, or run npx higherdata --version. Global flags are --json, --jsonl and --api-url <url>. --help and --version work without credentials or a config file.

Config lives at ~/.config/higherdata/config.json. The config helpers write it atomically with mode 0600 and tighten an existing file to 0600 when read. No config is created just by reading defaults. The format supports multiple profiles:

{
  "activeProfile": "staging",
  "profiles": {
    "production": { "apiUrl": "https://higherdata.io" },
    "staging": { "apiUrl": "https://staging.higherdata.io", "space": "default" }
  }
}

Each profile may also hold apiKey. URL precedence is --api-url, HIGHERDATA_API_URL, the active profile, then https://higherdata.io. HIGHERDATA_API_KEY overrides the profile key. API URLs require HTTPS. HTTP is allowed only on localhost, 127.0.0.1, and [::1] for local development. Embedded URL credentials are refused.

Exit codes: 0 success, 2 usage or configuration, 3 authentication, 4 limit, 5 suppressed-only result, 6 needs approval.

Interactive app

Run higherdata in a terminal to open the keyboard app. The yellow wordmark and three bars form in under 1.5 seconds; any key skips it. --no-banner opens the menu immediately. Piped output, --json, --jsonl and CI never animate. NO_COLOR disables accent colors. Supports 80 columns and wider, and responds to terminal resizing.

Use arrows and Enter to choose a section, tool, field or record. Search filters are editable fields: enter comma separated values for multi-value filters, and blank a field to clear it. Advanced structured fields accept JSON. N loads the next results page; Enter opens a record. Company records show contacts and Insights tabs (the server applies the plan gate and suppression). A adds the record to a saved list, F finds its work email, V verifies it.

Irreversible actions and email verification requests show a preview; scroll it with arrows and press Y to confirm or N to cancel. CRM writes use the server's change-set approval flow. Active enrichment jobs refresh at the server's interval while that screen is open. D streams a completed job or list export to a new private file. Escape goes back, Ctrl+C exits. A failed stream can leave a partial file.

Ask HigherData has private conversations per API key and space, separate from browser members. Enter a request, confirm verification or a CRM step with Y or cancel with N. Ctrl+B adjusts the conversation step limit; Ctrl+N starts a conversation. Model plans cannot approve or apply CRM changes.

Every registered tool is also available under tools with schema-derived flags and --input for advanced JSON. Searches, lookups and reversible local changes execute normally; irreversible actions and email requests preview by default and need --execute --yes to execute. The API validates inputs, authorization and suppression. Existing commands below preserve their behavior and output.

higherdata tools search.companies --country-codes CA,US --employee-count-min 50 --json
higherdata tools lookup.company --id hdo_EXAMPLE --json
higherdata tools email.verify --email [email protected] --json
higherdata tools email.verify --email [email protected] --execute --yes --json
higherdata tools changes.apply --id CHANGE_SET_ID --execute --yes --json
higherdata tools agent.run --action message --message "Find Canadian companies" --execute --yes --json

The tools commands and interactive app share the SDK transport. Each action gets a fresh idempotency key and has no automatic retries. For scripts, supply --idempotency-key to retry the same action; omit it in the interactive app, where multiple actions need different keys.

Commands

higherdata login --api-url https://staging.higherdata.io
higherdata whoami --json
higherdata use client-space
higherdata search companies --country-code CA --limit 25 --json
higherdata search people --country-code CA --title-keyword Operations --all --jsonl
higherdata search companies --where "Canadian companies" --employee-count-min 50
higherdata count --country-code CA --json
higherdata lookup company cedar.example --json
higherdata lookup person [email protected] --json
higherdata lists create "Canadian companies" --country-code CA --recurring --json
higherdata lists add <list-id> <opaque-id> --dry-run --json
higherdata lists run <list-id> --dry-run --json
higherdata lists export <list-id> --format csv --all > companies.csv
higherdata logout

Login prints the device code and approval URL to stderr, opens the browser when available, and polls at the server's interval until approval, denial or expiry. Use --no-browser for a remote terminal. Approval stores the issued key and API URL in the active profile with mode 0600. Login clears an older space selection; the issued key's space applies until use selects another authorized space. Logout removes the active profile's saved key. An environment key still applies.

Commands use only /api/v1. Versioned device routes reuse the original device handlers. Requests time out after 30 seconds, refuse redirects and cap response bodies at 8 MiB. The CLI reports safe errors without printing credentials or provider error bodies. Production's alias can use the canonical approval URL.

Repeat array flags, such as --country-code CA --country-code US, to add values. For advanced filters, use --filters '{"requiredKeywordGroups":[["operations","logistics"]]}'. The API validates filter fields and resolves tenant, space and scope. --where calls search.filters_from_text; explicit filter JSON and flags override its proposed values before the search. People searches need a selective country or industry, as enforced by the API.

--limit is the page size, from 1 to 50. --cursor resumes an opaque cursor and --all walks the remaining pages. Repeated cursors stop with an error. JSON search output retains items, nextCursor and zeroResults; with --all, the items are combined and the final cursor is null. JSONL prints one record per line. Human output uses tables. Choose one of --json and --jsonl.

List writes support --dry-run, which sends execute=false to the tool. List export emits the tool's CSV or JSONL content; --all combines pages with a single CSV header. Use --json to retain the export response envelope. Until background jobs are configured, executing lists run reports that jobs are unavailable; creating lists, adding items and exporting still work.

Bulk enrichment

Upload CSV or JSONL with explicit --map target=column options. Each upload request carries at most 500 rows. The server enforces the workspace's row and file limits and retains private files for seven days.

higherdata enrich companies.csv --operation enrich.company --map domain=Website --wait --output enriched.csv
higherdata enrich people.jsonl --operation email.verify --map email=work_email --wait --output verified.jsonl
higherdata jobs list --json
higherdata jobs get JOB_ID --json
higherdata jobs wait JOB_ID --json
higherdata jobs download JOB_ID --format csv --output results.csv
higherdata jobs cancel JOB_ID --dry-run --json

--dry-run uploads the input and checks its row count and mapping without enriching records. Output files must not already exist. Uploads, downloads, and lists export --all and suppress export --all stream bounded pages instead of buffering the full file. A failed stream can leave a partial destination; retry to a new file. jobs wait times out after one hour and prints the job id for continuation. Cancellation requires admin scope and settles only already completed work.

The enrich.bulk tool also accepts a saved list source and an optional tenant completion webhook. An admin configures the HTTPS URL and secret in the start request. The receiver verifies x-higherdata-signature (the sha256= prefix followed by the HMAC-SHA256 hex digest of timestamp + "." + rawBody) with the shared secret, checks x-higherdata-timestamp freshness, and deduplicates by job id. Delivery is retried from the durable outbox at most five times. Payloads contain job status and counts, not result records.

When background jobs are dormant, jobs wait advances bounded slices. With background jobs active, the same command observes progress. Downloads reapply current suppression and may omit records that were allowed when the job ran.

Agent installation

Open Account in the interactive app and choose Install MCP or Install skills. Select the agent and scope, then review the destination before confirming. The same operations work as commands:

higherdata --json mcp install claude
higherdata --json mcp install codex --profile full
higherdata --json mcp install cursor --scope project
higherdata --json mcp install codex --print
higherdata --json skills install claude
higherdata --json skills install codex --scope project

MCP uses the selected API origin's /mcp endpoint, selected space and either the default tool profile or ?profile=full. User installs use the saved CLI key in a private file unless HIGHERDATA_API_KEY is set, in which case the configuration references that environment variable. Project installs always use an environment reference. Set that variable in the environment that launches the agent. --print never shows a stored credential or edits files.

Claude Code uses its claude mcp add --transport http command when available, or prints a safe command to run manually. Codex uses ~/.codex/config.toml (project: .codex/config.toml). Cursor uses ~/.cursor/mcp.json (project: .cursor/mcp.json). Existing server entries are preserved, changed files are backed up privately, and identical installations are unchanged. An existing higherdata entry with different settings is left unchanged; remove it in the agent before reinstalling. Restart your agent after changing MCP.

The package includes five skills: building an ICP starter list, enriching a CSV safely, finding work emails, respecting suppression, and checking usage. Claude Code skills go to ~/.claude/skills or project .claude/skills; current Codex skills go to ~/.agents/skills or project .agents/skills. Customized installed skills are preserved. Move a customized skill aside before updating it from this bundle. Installs do not call HigherData.

Formats follow the current Claude Code MCP, Codex MCP, Cursor MCP, and Codex skills documentation.

Compatibility

The CLI reads public /api/v1/meta once per day per API origin and caches the policy beside its config file. Update notices are written to stderr only during interactive invocations. Versions below the server's minimum refuse commands and suggest higherdata update. update, login, --help and --version remain available without a compatibility check.

The metadata request times out after three seconds. On network failure the CLI uses its last known policy; with no cached policy it allows the command. Failed checks are cached for a day too. A read-only cache directory allows commands but cannot persist the daily check, so subsequent invocations may check again.

Download the loaded search page to a new file with higherdata search companies --country-code CA --out results.csv. Add --all to download up to 5,000 rows, or use a .jsonl destination for JSON Lines. The interactive results screen offers "This page" and "All results" when you press d. For larger sets, save the search to a list and export the list. Existing files are never overwritten.

Updates

Run higherdata update (alias higherdata upgrade) to check npm and install the latest stable release. The CLI installs the exact version it checked and prints the old and new versions. A permission failure prints npm's error summary and the manual command. It never retries with sudo.

Interactive npm global installs check npm on every run with a 1.5-second timeout, then automatically install a newer release and restart the same command with the same arguments. Failed installs print a manual command and continue on the current version. Timeouts and network failures continue silently. There is no cache for this npm release check.

Automatic updates are skipped when either stdin or stdout is not a TTY, CI is set, --json or --jsonl is used, for MCP or stdio protocols, and for npx or non-global installs. To opt out for an invocation, set HIGHERDATA_NO_AUTO_UPDATE=1. To persist the preference, run:

higherdata config set auto-update false
# Re-enable automatic updates
higherdata config set auto-update true

Explicit higherdata update remains available with an opt-out or a server minimum-version refusal. Users on 0.3.0 must reinstall once to obtain the update command: npm install --global higherdata@latest.

Credentials and diagnostics

The CLI stores saved API keys in macOS Keychain, Windows Credential Manager, or Linux Secret Service (for example GNOME Keyring or KWallet). Existing plaintext profiles migrate on first use. Config files retain only a keychain reference. On platforms without a supported keychain, or when a persistent Linux service is absent, the CLI keeps the existing file fallback with mode 0600. A missing native binding, locked store or inaccessible keychain returns an error rather than downgrading credentials. higherdata logout removes the active profile's keychain entry. HIGHERDATA_API_KEY remains available for CI.

Server failures print the error code, user-safe message and request id to stderr. JSON and JSONL results stay on stdout. Non-interactive commands also print a one-line newer-version notice on stderr using the existing daily compatibility check.

When higherdata tools email.find returns status: ambiguous, select an opaque id from companyCandidates and retry with --company-id. This choice does not submit verification requests. An exact match to one primary domain is selected automatically when the complete company match set is available.