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 <loc_id> --json
  curviate search jobs --company <id1>,<id2>,<id3> --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