higherdata 0.2.0

package/LICENSE

@@ -0,0 +1 @@
+Copyright HigherOps Inc. You may install and use this software with a HigherData account. You may not redistribute modified copies.

package/README.md

@@ -0,0 +1,224 @@
+# 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 `higherdata` and `hd`. 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:
+
+```json
+{
+  "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` (or `hd`) 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.
+
+```sh
+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 avery@cedar.example --json
+higherdata tools email.verify --email avery@cedar.example --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
+
+```sh
+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 avery@cedar.example --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.
+
+```sh
+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:
+
+```sh
+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](https://code.claude.com/docs/en/mcp),
+[Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli),
+[Cursor MCP](https://cursor.com/docs/mcp), and
+[Codex skills](https://learn.chatgpt.com/docs/build-skills) documentation.
+
+## Compatibility
+
+The CLI reads public `/api/v1/meta` once per day per API origin and caches the
+policy beside its config file. Updates are announced on stderr so JSON output
+stays machine-readable. Versions below the server's minimum refuse commands
+with `npm install --global higherdata@latest` as the upgrade command. `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.