higherdata 0.6.0 → 0.7.0

package/README.md

@@ -11,7 +11,7 @@ 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.
+`--help`, `--version` and `higherdata guide` 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.
@@ -37,6 +37,37 @@ 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.
 
+## Agent quick reference
+
+`higherdata guide` prints this on one screen. It does not call the API.
+
+Count first, then download. `higherdata count --country-code CA --json` estimates
+companies and their contacts. A people count is
+`higherdata tools search.count_people --input '{"filters":{"countryCodes":["CA"]}}' --json`.
+Then download once:
+
+```sh
+higherdata search people --country-code CA --title-keyword Operations --all --out people.jsonl
+```
+
+`--all` requests 500 rows per page (the largest page the API allows for a download) and keeps at
+most 3 pages ahead of the writer. Progress prints `344 rows` while it runs and
+`453 rows (all)` when every matching row is saved. The 5,000 row cap is mentioned
+only when a download hits it. Save the search to a list and export the list for
+a larger set. `--out` writes the same fields as `--jsonl`, whether the file is
+`.jsonl` or `.csv`. Do not download twice to recover missing columns.
+
+Filter flags are on `higherdata search people --help` and
+`higherdata search companies --help`. Allowed values come from
+`higherdata tools search.facets --json` (country, state, industry, NAICS,
+funding, department, seniority, role family, and city suggestions).
+`--where "Canadian software companies"` proposes filters before the search.
+A people search needs a country or an industry.
+
+Do not call `lookup.company` once per person. When batch company lookup is
+available, pass up to 100 `hdo_` ids in one `lookup.company` call. Until that
+call accepts `ids`, it takes one domain, name, LinkedIn URL, or `hdo_` id.
+
 ## Interactive app
 
 Run `higherdata` in a terminal to open the keyboard app. The yellow
@@ -72,6 +103,8 @@ 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 lookup person --linkedin https://www.linkedin.com/in/avery-orchid --json
+higherdata lookup company --linkedin https://www.linkedin.com/company/orchid-fixture --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
@@ -110,9 +143,11 @@ 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.
+handlers. Requests time out after 30 seconds and refuse redirects. Ordinary
+response bodies stay at 8 MiB. A search download page can be up to ten times
+that, matching a 500-row page. 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"]]}'`.
@@ -122,7 +157,8 @@ 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
+`--all` walks the remaining pages. A search download with `--all` always requests
+500 rows per page and sets download to true. 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`.
@@ -222,7 +258,7 @@ 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.
+Download the loaded search page to a new file with `higherdata search companies --country-code CA --out results.csv`. Add `--all` to walk every remaining page, up to 5,000 rows. `--all` requests 500 rows per page, keeps at most 3 pages ahead of the writer, and prints `344 rows` while it runs and `453 rows (all)` when the search is finished. The 5,000 cap is mentioned only when the download hits it. `.csv` and `.jsonl` files contain the same fields as `--jsonl` on stdout. 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. `higherdata guide` prints the same download recipes.
 
 ## Updates
 
@@ -259,3 +295,5 @@ The CLI stores saved API keys in macOS Keychain, Windows Credential Manager, or
 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.
+
+`higherdata verify-email --email avery@cedar.example --execute --yes` refuses an address already held for a contact. Existing record email status is read-only. API callers who explicitly need another verification can add `--force`; this override is not offered in the interactive app. Finds wait automatically for their verification result.