Foundation patterns for the `hubspot` CLI — JSONL piping, batch read, pagination, dry-run/digest/confirm for destructive ops, and `hubspot history` for recovery. Every other skill builds on this one.

Resources File When to use resources/json patterns.md Reshape patterns for turning a read into an update payload, a search into a delete list, a CSV into an upsert stream. Source of truth This is the hubspot agent CLI; the hs developer CLI ( @hubspot/cli ) is a different tool and does not manage CRM data or workflows. hubspot <command help is authoritative. If anything in this file contradicts help , trust help and tell the user. Run hubspot objects types once at the start of a session to see what object types exist in this portal (standard + custom). Submit Feedback Use the hubspot feedback command to send a message to the owners of this CLI tool. Pass source agent so it's attributed to agent traffic (it defaults to user ): This can be anything from: Specific bugs and hiccups you encountered Things you wish you knew before using the CLI Anything your user got confused, frustrated, or upset about Anything the user asked for that you couldn't do Any tools, capabilities, or skills you wish existed that would make future tasks easier It takes one short line, attaches to the active HubSpot account, and doesn't block the task — send it and keep going. Output shape Every read command ( list , search , get ) emits JSONL — one JSON object per line: properties email,firstname limits which fields the server returns under .properties . Downstream jq should use .properties.email , not .prop email . Write commands ( create , update , upsert , delete , merge , associations create ) accept JSONL on stdin and emit JSONL — one result per input line: {"id":"123","ok":true,"data":{...}} or {"id":"123","ok":false,"error":{"status":...,"message":"..."}} . Order of results matches input order. Read in batch — never one by one The CLI accepts multiple IDs natively. Never pipe IDs into xargs I{} hubspot objects get ... — that spawns one CLI process per record. A single hubspot objects get reads up to ~100 IDs per call via the batch endpoint. For more, page in chunks of 100. Bulk flow: paginate first, then reshape, then write When operating on all records of a type (or all matches of a filter), always start with pagination loop.sh — never run a bare list or search to "check how many there are." A bare call returns at most 100 records and you will have to re fetch them anyway. The canonical bulk pattern is: 1. Paginate all records to a JSONL file 2. Reshape with jq into the write payload 3. Pipe to the write command ( update , delete , etc.) with dry run first Pagination list and search return at most 100 records per call. Use resources/pagination loop.sh to collect all pages into a single JSONL file: Examples: The script pages through after cursors automatically, prints progress to stderr, and writes JSONL to the output file. Run it as a single foreground command — do not background it or reconstruct the loop inline. Write in batch — always pipe Write commands accept JSONL on stdin. The transformation between a read shape and a write shape is a jq reshape: Write command Required per line shape objects create {"properties":{"field":"value"}} objects update {"id":"123","properties":{"field":"value"}} objects upsert {"idProperty":"email","id":"jane@example.com","properties":{...}} (or use id property email once) objects delete {"id":"123"} objects merge {"primary":"123","secondary":"456"} associations create {"from":"contacts:123","to":"companies:456"} Use plural object names in from / to ( contacts: , not contact: ). Safe destructive workflow Every destructive op ( delete , merge , bulk update ) supports dry run . The gating depends on row count: ≤100 rows — dry run emits one preview line per record: Re run without dry run to execute. 100 rows — dry run emits a single BulkData line with a digest and an apply command hint : You must re run with digest <hash confirm <value within 5 minutes. The confirm value is the record count (deletes) or the secondary ID (merge). Read it off apply command hint . Three step pattern: Recovery via hubspot history Every destructive op (and its dry run) is logged locally. Check what happened in the last hour and what's reversible: history does not currently restore records — it's an audit log. If you deleted something by mistake, capture the history line and tell the user to restore via the UI. Upsert beats search then create For "create if missing, update if present" (the enrichment pattern), use upsert — one CLI call per record, no race condition: Rate limit hygiene There is no true batch endpoint behind update / delete / upsert — the CLI issues one API call per stdin line. Test with head n 50 before piping a 50k row file. If the API starts 429ing, the per line output will show {"ok":false,"error":{"status":429,...}} — split your input file and retry the failed lines. Common reshapes See resources/json patterns.md for the full set. The two you need 90% of the time: Known constraints Some destructive operations may be blocked under user OAuth (browser login); set HUBSPOT ACCESS TOKEN (private app token) when running deletes if the CLI returns a permission error. hubspot owners list returns CRM users; there is no teams object. For team level operations, group by hubspot owner id client side. No Lists API, no sequences/cadences API in the current CLI surface.

bulk-operations