Curviate: search and discovery

Search is where most workflows start: find the person, the company, the post or the posting, then
act on it. Two rules decide whether a search is trustworthy, and both fail silently when broken:
structured filters take opaque ids, never human text, and a single page is not the result set.

Command surface established against CLI 0.33.0.

Before any command

npm install -g @curviate/cli && curviate --version    # needs Node 18 or newer
curviate login --api-key <key>                        # or export CURVIATE_API_KEY
curviate account list --json                          # the acc_id for --account

• Credentials resolve flag > environment > stored profile (CURVIATE_API_KEY,

CURVIATE_BASE_URL, CURVIATE_ACCOUNT).

• **--profile <name> picks the stored credential set; --account <acc_id> picks which connected

LinkedIn account performs this command.** They answer different questions; pass either or both.
--account takes an id, never an account name.

• --json on anything you parse; --fields a,b,c to keep result sets small; --verbose

when a slim response looks suspiciously empty.

• Put global flags at the end of the command. Trailing placement is unambiguous on every version.
• Branch on the exit code, never on prose. See the table at the end.
• Search is a read. --mode/--max-age are refused here with unknown flag, exit 2. Retrieval

mode exists on four commands only, and none of them is a search (see curviate-profile).

Resolve filter terms first

Every id-taking filter (--location, --industry, --company, --school, --title on jobs,
--service-category) must be resolved before use:

curviate search parameters --type LOCATION --keywords "Germany" --limit 5 --json
curviate search people --keywords "AI engineer" --location <id> --limit 25 --json

**A filter value that is a name rather than an id is silently dropped and the search runs
unfiltered, at exit 0.** --location "Germany" has returned New York, Bengaluru and Toronto with
no warning. There is no error to branch on; the only defence is resolving first. Full parameter-type
list and the resolution quirks are in curviate-profile.

The search commands

--filters '<json>', --filters-file <path> and --filters - (stdin) submit a raw filter body on
people, companies, posts and jobs. Named flags win on conflict, and **the server body schema
is strict**: an unknown field is a 400, not an ignored key.

Traps

• **--industry is a company's registered LinkedIn industry, not a topic.** Pairing it with a

cross-cutting technology theme silently excludes nearly everything relevant: adding an
AI-flavoured industry filter to an otherwise identical function-plus-keywords search dropped a
result set from 6,360 to 18. Most companies hiring for an AI role are registered under "Software
Development" or "IT Services". Use --keywords and --function for themes; keep --industry for
genuine vertical targeting (healthcare, financial services, construction).

• search people --title is free-text; search jobs --title is id-based. Resolving a job-title

id and passing it to search people --title silently has no effect: the id is treated as a
substring that matches nothing useful.

• --network-distance and --location together have returned a 400 on search people. Pick

one or the other however the values were resolved.

• A salary threshold in the raw filter body is unreliable in low-transparency markets. In

Germany, three drastically different thresholds against the same search returned identical,
unfiltered counts with no error; LinkedIn's salary data is too sparse there to filter against.
Spot-check a filtered against an unfiltered count before qualifying leads by salary.

• Job postings can carry company: null, even under --verbose; agency and confidential

listings are a legitimate LinkedIn state. Skip them rather than assuming every result has a
company.

• Classic job search has no company-size filter. For "mid-size-or-larger companies hiring for X",

qualify by size first and then scope the job search to those companies:

```bash
curviate search companies --headcount 201-500,501-1000 --location --json
curviate search jobs --company ,, --function eng --json
```

The reverse direction (search jobs, then fetch each company to check size) works but is an N+1
with no batch lookup. Use it only when the posting itself is the entry point.

• --headcount 10001+ is not yet supported. Omit that bucket.

Groups

Pagination: one page is not the result set

There is no --page N.

Two output shapes, and they parse differently: a single page is an envelope
({"object": "…_list", "items": [...], "cursor": …}), while --all is NDJSON. Some searches add
paging.total_count.

--all can stop early. Its last stdout line is then
{"object": "stream_truncated", "pages_fetched": N, "has_more": true}. Check for that line before
treating a stream as exhaustive.

Full command surface

Read from the CLI's own --help at version 0.33.0. Descriptions, traps and confidence
tags elsewhere in this skill are hand-written and carry the version they were established against.

Every command below that takes flags at all also accepts --account, --api-key, --base-url, --beta, --fields, --json, --preview, --profile, --timeout, --verbose.

Exit codes to branch on here