Curviate: inbox and messaging

Messaging is the highest-consequence surface here: every send lands in a real person's inbox and cannot be unsent. Preview first, always.

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 sends this message. On a multi-account tenant, getting this wrong sends from the wrong person. Name the account explicitly on every write.
• --preview before every send. It renders the resolved request (recipient, text, acting account) without sending. On a read command it is refused with exit 2.
• --json on anything you parse; --fields a,b,c to project (a message carries 22 fields); --verbose when a slim response looks suspiciously empty.
• Put global flags at the end of the command.
• Branch on the exit code, never on prose. See the table at the end.

Text input

Message text is a positional argument, and - reads stdin. Use a quoted heredoc: the quoted delimiter disables every shell expansion, so apostrophes, accents, $ and backticks survive intact. An unquoted heredoc has produced an empty message that went out blank.

cat <<'EOF' | curviate message send "<chat_id>" - --preview
Hi Thomas,

thanks for connecting. I saw the work you shared last week.
EOF

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 source: store | live plus observed_at under --json, and a provenance: line on stderr in human mode. Read source rather than assuming.

• 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 chat may exist perfectly well on LinkedIn, this API just holds no copy. It is not "not found" (4), so re-checking the chat id is the wrong move, and it is not retryable as sent. Re-read with refill, auto or live.
• inbox messages: one bare --mode live page restarts the chat walk and leaves it unservable by cache_only afterwards. A listing is served from the store only over a closed walk. inbox messages --all walks to cursor: null and closes it. When you need a chat to be cache_only-servable later, reach for --all rather than a single live page.
• Every other command refuses the flags outright rather than ignoring them: unknown flag --mode, exit 2.

Reading: inbox

Listing chats does not mark anything read, so triage freely.

A chat item already carries the counterpart's identity: user_id (the ACoAA… member id), an embedded user{} (id, type, display_name, profile_url, public_picture_url), and name, the chat's own display name, which is populated on direct messages. Escalate to curviate profile <user_id> only for what user{} does not carry: headline, network distance, the full profile.

Traps

• --limit on inbox list and inbox messages is validated client-side to 1-25 (default 20). Outside that range the command exits 2.
• Neither inbox list nor inbox search reliably answers "does a chat with X exist". A single inbox list --limit 25 call has repeatedly omitted a chat created seconds earlier, across candidates, not a one-off race. inbox search has a different defect: its result set is ranked and capped rather than exhaustive, so a common first name can omit an exact match that a rarer name finds immediately. When the answer matters, walk inbox list by --cursor to exhaustion (or a generous --max-pages) rather than trusting one page or the search.
• Inbox threads carry no vanity slug. user.profile_url is built from the member id and public_identifier is absent even under --verbose. Join inbox-driven flows on the member id.
• inbox list has no date-range flags. --before/--after exist on inbox messages only, and filter messages within one chat. Filter a chat list client-side on last_message_timestamp.
• A very recent send or delete can take minutes to appear in inbox messages (LinkedIn-side indexing). message get <chat_id> <message_id> reflects it immediately, use that to confirm a send, not a re-list.

Discovering inboxes: inboxes

A COMPANY_… chat id sends as that page, with no extra flag. Pass it to message send and the message goes out from the page rather than from you; the output confirms with Sent as <name> (company page). Company inboxes are reply-only: they cannot start a conversation. The page's own admin inbox has a second, richer surface under company (see curviate-profile).

Sending: message

Chat ids look like CLASSIC_2-MzJmZTg1… for a personal chat and COMPANY_<id>_2-… for a page.

There is no idempotency key and no server-side de-duplication. A send that times out may already have landed. Re-read the thread (inbox messages, or message get for the id you just wrote) before re-issuing anything.

Event delivery: webhook

Message and account events arrive by webhook rather than by polling.

Verify the signature on every delivery before acting on its body.

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