Curviate: profiles, companies, and filter ids

Profiles are the entry point for almost every LinkedIn workflow: you resolve a person or a company, then act. This skill covers that resolution, the company page surface, the parameter lookup every structured search depends on, and the account plumbing underneath all of it.

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                          # verify: your connected LinkedIn accounts

• Resolve the binary first. If curviate --version fails, install it. Do not substitute a raw HTTP call for a command you could not find; the command surface is the contract.
• Credentials resolve flag > environment > stored profile. CURVIATE_API_KEY, CURVIATE_BASE_URL and CURVIATE_ACCOUNT are the right path for a scripted run: the key stays out of argv, out of ps, and out of shell history.
• --json on anything you parse. It is already the default when stdout is not a terminal; ask for it explicitly when a human might also be watching.
• --preview before every write. It renders the resolved request without sending it. On a read command it is refused with exit 2.
• --fields a,b,c to project. Profile responses carry 18 or more fields; projecting cuts most of that away.
• --verbose when a slim response looks suspiciously empty. An empty slim field is not proof the data does not exist; see Traps.
• Put global flags at the end of the command. Trailing placement is unambiguous on every version; a leading global flag has been dropped silently by older builds, running under whichever account was already active rather than the one you named.

`--profile` and `--account` are different questions

Both exist on every command and they answer different questions. Pass either, both, or neither:

--account takes an account id only; an account name comes back ACCOUNT_NOT_FOUND, exit 4. A structurally malformed value is refused at exit 2 before the request is built. Resolve ids live with curviate account list --json; they change when an account is reconnected, so never hard-code one.

Retrieval mode: `--mode` and `--max-age`

Exactly four reads decide between a stored copy and a live LinkedIn call: profile me, profile <id>, inbox get and inbox messages. Two of them are here.

--max-age <seconds> (0 to 31536000) overrides those presets in both directions; --max-age 0 is the same as --mode live.

Every response carries its provenance: source: store | live plus observed_at under --json, and a provenance: line on stderr in human mode. Read source rather than assuming.

curviate profile me --mode live --json          # source: live
curviate profile me --mode cache_only --json    # source: store, with observed_at

Three mechanics that decide whether a retrieval-mode call works:

• cache_only with --max-age is a usage error, exit 2, raised before any network call. cache_only never reaches LinkedIn at any age, so a freshness threshold cannot change its answer. Drop --max-age, or use --mode refill.
• cache_only on a store miss is exit 14 (NOT_STORED): the profile may exist perfectly well on LinkedIn, this API just holds no copy. It is not "not found" (4), so re-checking the identifier is the wrong move, and it is not retryable as sent. Re-read with --mode refill (fetch once, store it), auto, or live.
• Every other command refuses the flags outright rather than ignoring them: unknown flag --mode, exit 2. A retrieval-mode habit applied to search people fails loudly, which is the good case: you are never silently served an unintended freshness.

One same-named flag is unrelated: job publish --mode FREE|PROMOTED|PROMOTED_PLUS selects a publishing mode and spends money. It has nothing to do with retrieval.

`profile`: members

profile <id> accepts a vanity slug, a full profile URL (country subdomains such as de.linkedin.com included), a URN, a native member id (ACoAA…), or me.

profile follow, unfollow, relations, followers and following belong to the network workflow; see curviate-network.

Traps

• --sections returns zero items unless you also pass --verbose. The slim projection strips the section payload even when you asked for that exact section. Always pair them.
• emails and phone_numbers need --verbose, and --fields does not escalate for you. profile <id> slim strips both; profile me slim keeps emails and drops phone_numbers. --fields emails,phone_numbers without --verbose returns {} and a stderr warning, which reads exactly like "this member published no contact details". It is not.
• Contact fields are gated on first-degree connection, and absent rather than empty below it. At second degree emails and social_handles are missing from the response entirely and phone_numbers is []. Fetch from whichever account is actually connected, and re-fetch after an invitation is accepted. A profile read costs the same either way, so pass --verbose up front rather than paying for two reads.
• specifics.throttled_sections is --verbose-only, and it is a correctness signal. It names the sections LinkedIn rate-limited on this request. Without it you cannot tell "this member has no listed experience" from "the experience section was throttled, retry it". Read it before treating an empty section as ground truth, and requery only sections that actually appear in it.
• A missing member and a premium-gated member are indistinguishable on a non-premium account. A nonexistent slug returns LINKEDIN_FEATURE_NOT_SUBSCRIBED, exit 5, never 404/exit 4. Deep reads of some out-of-network members hit the same gate even though the search that found them needed no subscription at all. Verify a handle through search people before concluding that a subscription would fix it.
• profile update --headline reads back on the description field, and there is no --description flag. The write takes --headline; the read response mirrors that text under description ("NOT the About/Summary section", which is bio). --fields headline on a read matches nothing and is silently dropped like any unmatched path; project it as --fields description.
• A profile write can take minutes to about two and a half hours to appear on read-back. A profile update returning exit 0 was accepted. A stale-looking read immediately after is not evidence the write failed.
• A profile fetch is a real, member-visible profile view and consumes the account's daily profile-view allowance. Do not fetch speculatively in a loop.
• Never write profile me relations. The command is profile relations. Older builds silently discarded relations and answered with your own profile at exit 0; current builds exit 2.

`company`: company pages

company <id> takes a slug, URL or numeric id. Its sub-resources need the numeric provider id returned by that first call, so it is always two steps.

follow-invite is all-or-nothing. A request where every invitee id is valid returns one outcome per invitee in request order (invited, already_invited, ineligible, not_found). A single invalid id rejects the whole request with a 404 rather than a partial result. Re-inviting someone already invited is a safe no-op that returns the same invitation id, never a duplicate.

`search parameters`: turning words into filter ids

Structured search filters take opaque ids, not human text. Resolve first, then search.

curviate search parameters --type LOCATION --keywords "Germany" --limit 5 --json
curviate search people --location <id> --keywords "AI engineer" --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 results from New York, Bengaluru and Toronto with no warning at all. Resolve every --location, --industry, --company and --school value through this command first.
• JOB_FUNCTION returns string tokens (eng, sale), not numeric ids, unlike every other type. Pass the string straight into search jobs --function.
• --type PEOPLE is a working name-to-member lookup and returns real member profiles; it is also how you resolve search people --followers-of.
• Results carry both id and public_identifier, so they chain directly into a connect or a message.

Session and connected accounts

Zero connected accounts is a valid state, not an error: a fresh tenant authenticates fine and account list returns an empty list. Every account-scoped command is unusable until an account is connected.

Verify each account, not just the first. account list proves an account exists and reads status: "active"; it does not prove the session round-trips. For each id:

curviate profile me --account <acc_id> --fields first_name,last_name,description --json

Exit 0 with a populated name proves auth, account scoping and field projection work together.

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 --json.

Exit codes to branch on here

Branch on the exit code, never on the message text. Under --json an error prints {"error": {"code", "message", …}}.