@revfleet/hscli 0.8.11 → 0.9.0

package/docs/COOKBOOK.md

@@ -11,7 +11,7 @@ All write operations are **dry-run by default**. Omit flags to see the safety er
 ### Login with a private app token
 
 ```bash
-hscli auth login --token "pat-eu1-a1b2c3d4-5678-9abc-def0-1234567890ab"
+printf '%s' "$HUBSPOT_PRIVATE_APP_TOKEN" | hscli auth login --token-stdin
 ```
 
 Hublet is auto-detected from the token prefix (e.g. `pat-eu1-...` routes to `api-eu1.hubapi.com`).
@@ -80,14 +80,21 @@ hscli auth oauth-url \
 ### Exchange an OAuth code for a token
 
 ```bash
+: "${HSCLI_OAUTH_CLIENT_SECRET:?set HSCLI_OAUTH_CLIENT_SECRET in your secret manager}"
 hscli auth oauth-exchange \
   --client-id "a1b2c3d4-5678-9abc-def0-1234567890ab" \
-  --client-secret "secret-value" \
   --code "auth-code-from-redirect" \
   --redirect-uri "https://app.example.com/oauth/callback" \
   --profile oauth-prod
+
+hscli --profile oauth-prod auth whoami
 ```
 
+The access token refreshes automatically before expiry. hscli stores the
+refresh token and the client-secret environment variable name, never the
+client secret itself. Use `hscli --profile oauth-prod auth refresh` to force a
+rotation while diagnosing an OAuth installation.
+
 ---
 
 ## 2. CRM Operations (Contacts, Companies, Deals, Tickets)
@@ -230,6 +237,13 @@ hscli crm custom-objects records create vehicles --force \
   --data '{"properties":{"vin":"1HGCM82633A004352","make":"Honda","model":"Accord"}}'
 ```
 
+### Batch-create custom object records
+
+```bash
+hscli crm custom-objects records batch-create vehicles --force \
+  --data '{"inputs":[{"properties":{"vin":"1HGCM82633A004352","make":"Honda","model":"Accord"}}]}'
+```
+
 ### Search custom object records
 
 ```bash
@@ -310,6 +324,22 @@ hscli crm migration export-metadata \
 
 This captures property groups with their real labels/displayOrder, property definitions, deal/ticket pipelines with per-stage detail, custom object schemas, owners, teams, business units, currencies, and standard association labels. Use it before building replay payloads so pipeline IDs/stage IDs and owner/team mappings are explicit.
 
+### Apply migration ID maps to local payloads
+
+```bash
+hscli crm migration id-map apply \
+  --data @contacts-upsert.json \
+  --field hubspot_owner_id=./id-maps/owners.json \
+  --field sales_owner=./id-maps/owners.json \
+  --field hs_owning_teams=./id-maps/teams.json \
+  --field hs_all_assigned_business_unit_ids=./id-maps/business-units.json \
+  --on-unmapped error \
+  --out contacts-upsert.remapped.json \
+  --report-out contacts-upsert.remap-report.json
+```
+
+`id-map apply` rewrites local JSON only; it never calls HubSpot. It supports `{ inputs: [...] }` batch payloads, arrays, and single records. Use `--on-unmapped error` for final migrations. Use `--on-unmapped drop` only after documenting an explicit policy, for example dropping out-of-scope teams while preserving all mapped NA/GLO teams.
+
 ### Export recoverable record activities
 
 ```bash
@@ -363,7 +393,7 @@ hscli --force crm properties batch-create contacts \
   --data @contacts-properties.json
 ```
 
-`batch-create` skips `hs_*` reserved names, HubSpot-defined/read-only properties, and empty enumerations by default. It also removes enum options with blank labels/values before sending. If you prefer to keep a property whose enum options cannot be recovered, demote it to a free-text property:
+`batch-create` skips HubSpot-reserved names (`hs_*`, `recurring_revenue_*`, and known reserved close-reason names), HubSpot-defined/read-only properties, and empty enumerations by default. It also removes enum options with blank labels/values before sending. Owner-reference enum properties keep `referencedObjectType` and automatically get `externalOptions: true`, which HubSpot requires for object-reference options. If you prefer to keep a property whose enum options cannot be recovered, demote it to a free-text property:
 
 ```bash
 hscli --dry-run crm properties batch-create contacts \
@@ -378,6 +408,8 @@ hscli --force crm properties batch-create 2-123456 \
   --data '{"inputs":[{"name":"migration_region","label":"Migration Region","type":"string","fieldType":"text","groupName":"customobjectinformation"}]}'
 ```
 
+Do not use `crm custom-objects schemas update` to add properties to an existing custom object schema. HubSpot accepts that PATCH but silently ignores the `properties` array, so hscli now fails early and points you to `crm properties batch-create <objectType>`.
+
 ### Update a property label
 
 ```bash
@@ -398,6 +430,16 @@ hscli crm associations create deals 18294750312 companies 9182736450 --dry-run
 hscli crm associations create deals 18294750312 companies 9182736450 --force
 ```
 
+### Batch-create typed associations
+
+```bash
+hscli crm associations batch-create contacts companies --dry-run \
+  --data '{"inputs":[{"from":{"id":"101"},"to":{"id":"202"},"types":[{"associationCategory":"HUBSPOT_DEFINED","associationTypeId":279}]}]}'
+
+hscli crm associations batch-create contacts companies --force \
+  --data @contact-company-associations.json
+```
+
 ### Remove an association
 
 ```bash
@@ -505,6 +547,9 @@ hscli forms create --source-format v2 --strict --dry-run \
 
 hscli forms translate-v2 --data '{"name":"Legacy Webinar Signup","submitText":"Register","formFieldGroups":[{"fields":[{"name":"email","label":"Email","fieldType":"email","required":true}]}]}'
 
+hscli forms create --source-format v2 --subscription-type-map ./id-maps/subscription-types.json --dry-run \
+  --data '{"name":"Legacy Webinar Signup","formFieldGroups":[{"fields":[{"name":"email","label":"Email","fieldType":"email"}]}]}'
+
 hscli forms update "f47ac10b-58cc-4372-a567-0e02b2c3d479" --force \
   --data '{"name":"Q2 Webinar Signup (Updated)"}'
 ```
@@ -540,6 +585,9 @@ hscli workflows flows get 39172845
 
 hscli workflows flows create --dry-run \
   --data '{"name":"New Lead Nurture Sequence","type":"PLATFORM_FLOW"}'
+
+hscli workflows preflight --id-map-dir ./id-maps --strict \
+  --data '{"name":"Workflow export","actions":[],"suppressionListIds":[]}'
 ```
 
 ### Service conversations and feedback
@@ -805,13 +853,86 @@ The MCP server exposes the same operations as the CLI with the same safety model
 Use Claude-style slash commands when you want the CLI to tell you the next safe sequence:
 
 ```bash
+hscli ui
 hscli /setup
 hscli /migration
 hscli /read
+hscli /fetch
+hscli /get
 hscli /write
 hscli /guardrails
 ```
 
+### Render an agent-safe runbook
+
+Use `agent plan` when Codex, Claude Code, Cursor, or a scheduled worker needs a
+deterministic HubSpot operator sequence. The command prints a plan; it does not
+call HubSpot.
+
+```bash
+hscli agent list
+hscli --profile sandbox --policy-file ./policy.json --change-ticket CHG-123 \
+  agent plan automation-risk --json
+```
+
+Render a schedule artifact without installing it:
+
+```bash
+hscli --profile live agent schedule render pipeline-risk \
+  --target cron \
+  --cron "0 8 * * 1"
+```
+
+Available recipes:
+
+- `data-cleanup` — fill-rate, lifecycle, ownership, and audit review
+- `pipeline-risk` — pipeline/stage metadata and deal data-quality review
+- `automation-risk` — workflow inventory, workflow errors, email exposure, and audit review
+
+Every follow-up command still goes through the normal hscli model: public APIs
+first, `--force` for writes, optional `--policy-file`, optional
+`--change-ticket`, shared rate-limit handling, redacted trace/audit output.
+
+### Build a portal context pack
+
+Use `context build` before handing a portal to an agent or migration runbook. It
+performs a small read-only public-API probe and returns deterministic signals:
+portal metadata, owner/team counts, workflow count, CRM object totals/samples,
+profile classification, recommended runbooks, and questions to ask the portal
+owner before writing anything.
+
+```bash
+hscli --profile source-read --json context build --sample-limit 25
+```
+
+### Manage several portals safely
+
+Use `portals list` to see the local profile inventory without printing tokens or
+calling HubSpot. Use `portals plan` when a source/sandbox/live workflow needs
+the same read-only context or agent runbook across several portals.
+
+```bash
+hscli --json portals list
+hscli --json portals plan \
+  --profiles source-read,sandbox-read \
+  --runbook automation-risk \
+  --include-context \
+  --sample-limit 25
+```
+
+The output is plan-only: every rendered command includes an explicit
+`--profile`, so source and target portals stay separate.
+
+### Check API coverage parity
+
+Use `doctor parity` to see which HubSpot areas hscli covers through public APIs,
+which require explicit browser-session/internal adapters, which are hybrid, and
+which remain UI-only/manual evidence.
+
+```bash
+hscli --json doctor parity
+```
+
 ### Check hublet configuration consistency
 
 Verifies that hscli's detected hublet, token prefix, and `@hubspot/cli` config all agree:
@@ -847,6 +968,7 @@ All commands support `--format` and `--json` flags.
 
 ```bash
 hscli crm contacts list --format json
+hscli crm contacts list --format jsonl  # one compact envelope per result
 hscli crm contacts list --format csv
 hscli crm contacts list --format yaml
 hscli crm contacts list --format table   # default
@@ -870,8 +992,8 @@ hscli --telemetry-file ./telemetry.jsonl crm deals create --force \
 ### Manage staging and production side by side
 
 ```bash
-hscli auth login --token "pat-na1-staging-token" --profile staging
-hscli auth login --token "pat-eu1-production-token" --profile production
+printf '%s' "$HUBSPOT_STAGING_TOKEN" | hscli auth login --token-stdin --profile staging
+printf '%s' "$HUBSPOT_PRODUCTION_TOKEN" | hscli auth login --token-stdin --profile production
 
 # Read from staging
 hscli --profile staging crm contacts search --query "test"