@revfleet/hscli 0.8.11 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,191 @@
 # Changelog
 
+## Unreleased
+
+## 0.9.0 - 2026-07-09
+
+**Agent-safe operator release.** hscli now wraps its broad HubSpot command
+surface in deterministic execution primitives suitable for consultants,
+scheduled operations, Codex, Claude, and other MCP clients. The CLI remains the
+only operation layer; agents receive scoped tools and verifiable plans instead
+of a second implementation of HubSpot writes.
+
+### Added — streamable agent output
+
+- Added `--format jsonl`. Arrays and HubSpot result pages emit one compact,
+  redacted envelope per item, with paging metadata repeated on each line.
+- Errors use the same one-line envelope contract, making long reads and
+  scheduled runs safe to stream into shell pipelines and evidence stores.
+
+### Added — action contracts and evidence runbooks
+
+- Added versioned `hscli.action-contract/v1` action contracts. Contracts bind
+  exact argument arrays to profile, portal, expiry, optional change ticket,
+  verification command, deterministic ID, and SHA-256 digest.
+- Added `agent contract create|inspect|verify|apply`. Apply is plan-only unless
+  both `--execute` and global `--force` are present; execution uses
+  `shell:false` and runs the contract's read-only verification command.
+- Added `agent run <recipe>` with `--resume` and `--continue-on-error`.
+  Runbooks write a manifest, checkpoint, JSONL event ledger, per-step output,
+  and request telemetry, so interrupted diagnostics resume without repeating
+  completed work.
+- Schedule renderers now invoke the evidence-producing runbook path rather than
+  printing a plan and calling that execution.
+- Added `portal-baseline`, a one-command read-only activation runbook covering
+  portal identity, API reachability, users, teams, deal pipelines, CRM data
+  readiness, workflows, and request evidence. `--continue-on-error` preserves
+  a useful bundle when a token lacks one optional scope.
+
+### Added — MCP surface profiles
+
+- Added `minimal`, `crm`, `migration`, and `full` MCP surface profiles. New
+  servers default to `minimal`; raw `hub_api_request` is registered only on
+  `full`.
+- Added `hscli mcp --surface <profile>` and `HSCLI_MCP_SURFACE`, plus a generated
+  tool catalog documenting each tool's domain, operation class, and surfaces.
+- Registration-time filtering reduces agent context, accidental capability
+  exposure, and cross-purpose tool selection while preserving the complete
+  surface for explicit operator use.
+
+### Added — production OAuth profiles
+
+- OAuth code exchange and refresh now use HubSpot's `/oauth/2026-03/token`
+  endpoint and support the current `scopes[]`, `hub_id`, and `user_id` response
+  fields while retaining legacy scope-response compatibility.
+- OAuth access tokens refresh automatically before expiry. Concurrent requests
+  share one refresh, rotated credentials are persisted atomically, and failed
+  refreshes leave the previous profile untouched.
+- Client secrets remain in a named environment variable; only the variable
+  name is persisted. `auth whoami` reports identity/routing/expiry without
+  tokens, and `auth refresh` provides an explicit diagnostic rotation.
+
+### Changed — product contract
+
+- Positioned hscli as a HubSpot operations and migration control plane with
+  evidence, rather than leading only with endpoint count.
+- Replaced universal idempotency claims with the implemented model:
+  endpoint-aware retries reuse a correlation key, while action contracts and
+  read-only verification protect broader approved write workflows.
+- Added package-contract tests that keep install instructions, output formats,
+  OAuth commands, nested documentation, generated MCP catalog, and product
+  claims aligned with the shipped binary.
+
+### Added — internal capture catalogue
+
+- Added a versioned allowlist module for HubSpot browser-session internal
+  capture surfaces, with validation that every POST endpoint is explicitly
+  tagged as a read-like search, preview, batch-read, async resolve, or Chirp RPC
+  read.
+- Added `hscli internal coverage`, a plan-only JSON control sheet that connects
+  the full internal endpoint docs, discovery log, allowlisted capture module,
+  surface counts, parameterized endpoints, and promotion policy for future
+  guarded write/replay adapters.
+- Added the account/security internal capture surface for account metadata,
+  security settings, installed apps, and sync-bridge inventory.
+- Expanded allowlisted internal capture coverage for report favorites/template
+  discovery, async report-result polling, workflow editor helpers
+  (permission checks, filter descriptions, card positions), and sales-content
+  detail reads for sequences, sales templates, and playbooks.
+- Documented how `backup plan` orchestrates HubSpot 360 backups while
+  `internal capture` performs the allowlisted read-only browser-session pulls.
+
+### Fixed — internal-adapter safety + dependency audit
+
+- Browser-session/internal adapters now share one hardened session resolver:
+  `--ui-domain` is allowlisted to HubSpot app hosts only
+  (`app.hubspot.com`, `app-eu1.hubspot.com`, etc.), and cookie exports are
+  filtered to the selected HubSpot domain before use.
+- `reports pull email-recipients` always requests `email` internally when
+  enriching recipients via contact batch-read, but only emits the contact
+  properties explicitly requested by the operator.
+- `seed` no longer revises or pushes live arbitrary existing CMS pages; CMS
+  revision/publish attempts are limited to pages created by the current seed
+  run.
+- `scripts/test-portal-writes.mjs` now requires `HSCLI_ALLOW_WRITE_PROBE=1`
+  before running, skips existing-resource mutation by default, and keeps
+  publish endpoints behind a separate opt-in.
+- Refreshed `package-lock.json` to clear current npm/Dependabot advisories for
+  `fast-uri`, `hono`, `ip-address`, and `express-rate-limit`.
+- Tightened the tracked Python demo-capture dependencies to published current
+  lower bounds (`pillow>=11.3.0`, `playwright>=1.59.0`) so GitHub does not keep
+  alerting on broad/invalid vulnerable ranges.
+
+### Added — reusable report pulls
+
+- Added `hscli reports pull object-fill-rate` for CRM object property fill-rate
+  audits, with optional all-property schema discovery.
+- Added `hscli reports pull property-distribution` for one-property value
+  distributions and blank-rate checks.
+- Added `hscli reports pull email-recipients` for per-recipient marketing email
+  event pulls across selected campaign IDs (`SENT`, `DELIVERED`, `BOUNCE`,
+  `OPEN`, `CLICK`, `DROPPED`, `SUPPRESSED`, `DEFERRED`) with optional contact
+  property enrichment.
+- Added `hscli reports pull source-target-parity` to compare object counts
+  between source and sandbox profiles.
+
+### Fixed — communication preferences v4 paths
+
+- Corrected `communication-preferences v4` endpoints to use HubSpot's
+  documented `/communication-preferences/v4/...` path. `subscriptions-list`
+  now reads `/communication-preferences/v4/definitions`.
+
+### Discovered — subscription definition migration
+
+- Public subscription definition reads work via
+  `GET /communication-preferences/v3/definitions` and
+  `GET /communication-preferences/v4/definitions`, but public creates return
+  HTTP 405 on `/communication-preferences/v3/definitions` and
+  `/communication-preferences/v4/definitions`.
+- Browser-session replay for Email > Subscription Types uses the internal
+  endpoint `/api/subscriptions/v1/definitions?portalId=<portalId>`.
+  Migration tooling must match definitions by
+  `name + purpose/process + communicationMethod/channel + businessUnitId`, not
+  by name alone, and remap business-unit IDs before write.
+- `communication-preferences definitions create --skip-existing` now uses that
+  composite match instead of skipping by name alone.
+- Added `communication-preferences definitions create-internal`, an explicit
+  browser-session migration adapter for Email > Subscription Types creation via
+  `/api/subscriptions/v1/definitions?portalId=<id>`.
+- Added `doctor internal-adapters` to list supported/planned internal
+  setup/migration adapters and keep them separate from generic raw API access.
+
+## 0.8.12 - 2026-04-24
+
+**Terminal operator home + `/fetch` alias.** Two incremental adds on
+top of 0.8.11's operator surface.
+
+### Added — terminal operator home
+
+- `hscli ui` / `hscli home` — opens a terminal home screen showing
+  the current profile's role, read/write safety state, policy + trace
+  status, API-usage guidance, and a recommended next command. Works
+  as a landing surface for "what should I do next on this portal?".
+
+### Added — `/fetch` (`/get`) slash command
+
+- Added to the Claude-style operator set (now `/setup`, `/migration`,
+  `/read`, `/fetch` / `/get`, `/write`, `/guardrails`). Thin alias
+  over read-shaped commands so agents can pick up HubSpot records
+  with the same grammar they use to read vault state.
+
+### Added — migration replay hardening
+
+- Legacy forms/v2 consent replay now extracts `metaData[].legalConsentOptions`,
+  preserves `submitButtonText`, and requires target subscription remaps via
+  `--subscription-type-map` unless `--allow-unmapped-consent` is passed.
+- `communication-preferences definitions list|create` can replay subscription
+  definitions with business-unit remapping (`--business-unit-map`,
+  `--business-unit-mode strict|drop|preserve`) and `--skip-existing`.
+- `settings business-units capture` reads the internal
+  `/api/business-units/v1/business-units` browser-session endpoint and can emit
+  a source-ID keyed id-map seed for subscription-definition BU remapping.
+- `workflows preflight` checks workflow exports against migration id-maps before
+  replay, including actions, enrollment criteria, suppression lists, custom
+  objects, association labels, users/owners, sequences, lists, subscriptions,
+  campaigns, marketing emails, and pipeline/stage IDs.
+
+Migration replay regression tests added.
+
 ## 0.8.11 - 2026-04-24
 
 **Migration operator surface + shared rate-limit enforcement.** Ships

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>Your HubSpot portal, in one binary.</strong>
+  <strong>The agent-safe HubSpot operator.</strong>
 </p>
 
 <p align="center">
@@ -24,10 +24,21 @@
 
 ## Why
 
-1,180 HubSpot endpoints, one TypeScript binary. Every write blocked unless you explicitly `--force` it. Every request auditable. Token stays on your machine. MCP-ready for Claude Desktop, Cursor, and any agent that speaks the protocol.
+`hscli` is a HubSpot operations and migration control plane for humans and
+agents. Every write is blocked unless you explicitly `--force` it. Every
+request can produce local audit evidence. Tokens stay on your machine. The same
+operation layer serves the CLI, deterministic runbooks, and scoped MCP tools.
 
 No SaaS middleman, no proprietary dashboard, no "download the CLI, then also install the desktop app". Just a CLI that respects production.
 
+HubSpot is moving toward an agent-ready platform: APIs, MCP, CLI, and open
+connectors so agents can run on HubSpot and run HubSpot. `hscli` is the
+operator layer for that world: public API first, MCP-compatible, scheduled
+runbooks, deterministic scoring, trace/audit evidence, migration adapters, and
+explicit write guardrails. It is not a generic internal API tunnel; internal
+browser-session surfaces stay allowlisted and task-specific for backup,
+migration, and setup work.
+
 ## Install & auth
 
 ```bash
@@ -45,25 +56,204 @@ printf '%s' "$HUBSPOT_TOKEN" | hscli auth login --profile live --token-stdin --h
 hscli auth set-hublet live eu1
 ```
 
+OAuth developer-app profiles use HubSpot's date-based token endpoint and
+refresh automatically before expiry. Store the client secret in an environment
+variable; hscli persists only the variable name:
+
+```bash
+export HSCLI_OAUTH_CLIENT_SECRET="..."
+hscli auth oauth-url --client-id "$CLIENT_ID" --redirect-uri "$REDIRECT_URI" \
+  --scopes "crm.objects.contacts.read"
+hscli auth oauth-exchange --client-id "$CLIENT_ID" --code "$AUTH_CODE" \
+  --redirect-uri "$REDIRECT_URI" --profile oauth-prod
+hscli --profile oauth-prod auth whoami
+```
+
+## First proof in one command
+
+Run the read-only portal baseline before learning the full command tree. It
+captures portal identity and API reachability, users and teams, deal pipelines,
+data readiness for contacts/companies/deals, and workflow exposure:
+
+```bash
+hscli --profile client-readonly agent run portal-baseline \
+  --output ./evidence/portal-baseline \
+  --continue-on-error
+```
+
+The output is a portable evidence bundle, not an AI summary: `manifest.json`
+records the exact steps and completion state, `requests.jsonl` records redacted
+HubSpot request telemetry, `events.jsonl` records runbook progress, and
+`steps/*.stdout.jsonl` preserves every deterministic result. Missing scopes are
+kept as explicit failed steps while the rest of the baseline continues.
+
 ## Operator workflows
 
 Start from intent instead of memorizing the whole command tree:
 
 ```bash
+hscli ui           # terminal home: profiles, safety, next action, workflows
 hscli /setup       # auth, hublet routing, scopes, capabilities
 hscli /migration   # portal/schema migration sequence
 hscli /read        # source-portal read workflow
+hscli /fetch       # get records or metadata without mutation
+hscli /get         # alias for /fetch
 hscli /write       # target-portal write workflow
 hscli /guardrails  # read-only, policy, trace, scope checks
+hscli /backup      # 360-degree portal backup workflow
 ```
 
+Agent-safe operator runbooks give Codex/Claude/Cursor deterministic plans
+instead of open-ended portal access:
+
+```bash
+hscli agent list
+hscli agent plan portal-baseline --json
+hscli agent plan automation-risk --json
+hscli --profile sandbox agent run automation-risk --output ./evidence/automation-risk
+hscli --profile sandbox agent run automation-risk --output ./evidence/automation-risk --resume
+hscli --profile sandbox --policy-file ./policy.json --change-ticket CHG-123 \
+  agent plan data-cleanup --json
+hscli --profile live agent schedule render pipeline-risk \
+  --target cron --cron "0 8 * * 1"
+```
+
+Runbooks are public-API-first, MCP-compatible, schedule-renderable, and
+auditable. `agent plan` never calls HubSpot; it prints the exact read/report
+commands. `agent run` executes those argument arrays with `shell:false` and
+writes a manifest, checkpoint, per-step output, request telemetry, and JSONL
+event ledger. `--resume` skips completed steps; `--continue-on-error` preserves
+partial evidence while finishing the remaining diagnostics.
+
+For approved fixes, seal the exact hscli argv in a versioned action contract.
+Contracts are offline-verifiable and bind execution to one profile, portal,
+expiry, and optional change ticket. They never contain tokens or shell text:
+
+```bash
+hscli --json agent contract create --input ./action-draft.json | jq '.data' > ./action-contract.json
+hscli --json --profile sandbox agent contract verify ./action-contract.json
+hscli --json --profile sandbox agent contract apply ./action-contract.json
+hscli --json --profile sandbox --force agent contract apply ./action-contract.json --execute
+```
+
+`apply` remains plan-only unless both `--execute` and global `--force` are
+present. Approved operations use argument arrays with `shell:false`, then run
+the contract's read-only verification command.
+
 Scope checks are built in:
 
 ```bash
 hscli doctor scopes diff --required real-mirror-read
 hscli doctor scopes explain sales-email-read
+hscli doctor parity
+```
+
+Multi-portal management stays local and plan-only by default. Use it when you
+manage source/sandbox/live profiles, global + regional portals, or many client
+tenants and want every command to keep an explicit profile boundary:
+
+```bash
+hscli --json portals list
+hscli --json portals plan \
+  --profiles live,sandbox \
+  --runbook automation-risk \
+  --include-context \
+  --sample-limit 25
 ```
 
+`portals plan` does not call HubSpot. It renders one `context build` and one
+`agent plan` command per profile so Codex/Claude/scheduled workers can operate
+without cross-tenant ambiguity.
+
+Reusable reporting pulls are built in for audits, migration checks, and
+matchback files:
+
+```bash
+hscli reports pull object-fill-rate --object contacts --limit 5000
+hscli reports pull property-distribution --object contacts --property lifecyclestage
+hscli reports pull email-recipients \
+  --campaign-ids 407801550,407801857 \
+  --event-types sent,delivered,bounce,open,click,dropped,suppressed,deferred \
+  --contact-properties email,firstname,lastname,company,lifecyclestage,hs_all_assigned_business_unit_ids
+hscli reports pull source-target-parity \
+  --source-profile live-readonly --target-profile sandbox-read --objects contacts,companies,deals
+```
+
+Full-portal backup planning is available for downgrade, migration, and forensic
+archive work. It is designed as a HubSpot 360 capture model: CRM, engagements,
+marketing, sales, service, CMS, commerce, automation, reporting, settings,
+integrations, files, and governance. It renders the public API capture runbook
+plus the explicit internal/browser-session brief without making HubSpot calls.
+The allowlisted internal endpoint catalogue lives in
+[`docs/INTERNAL_ENDPOINTS.md`](docs/INTERNAL_ENDPOINTS.md), with the full
+discovery archive in [`docs/INTERNAL-ENDPOINTS.md`](docs/INTERNAL-ENDPOINTS.md)
+and [`docs/INTERNAL-ENDPOINTS-DISCOVERY.md`](docs/INTERNAL-ENDPOINTS-DISCOVERY.md):
+
+```bash
+hscli --profile source-readonly backup plan \
+  --portal-id "$PORTAL_ID" \
+  --out-dir "$HOME/client-migration-assets/portal-$PORTAL_ID-full-backup" \
+  --include-internal \
+  --json
+```
+
+When the operator has an authenticated HubSpot browser session, the catalogue
+can be turned into a read-only allowlisted capture. Placeholder-heavy endpoints
+are skipped into the manifest instead of guessed:
+
+```bash
+hscli --json internal surfaces
+hscli --profile source-readonly --json internal coverage \
+  > "$HOME/client-migration-assets/portal-$PORTAL_ID-full-backup/internal-coverage.json"
+hscli --profile source-readonly --json internal capture \
+  --surface business-units \
+  --portal-id "$PORTAL_ID" \
+  --cookie-file "$HUBSPOT_COOKIE_FILE" \
+  --out-dir "$HOME/client-migration-assets/portal-$PORTAL_ID-full-backup/internal-api"
+hscli --profile source-readonly --json internal capture \
+  --all \
+  --portal-id "$PORTAL_ID" \
+  --cookie-file "$HUBSPOT_COOKIE_FILE" \
+  --out-dir "$HOME/client-migration-assets/portal-$PORTAL_ID-full-backup/internal-api/allowlisted-capture"
+```
+
+For internal read-like POST/RPC endpoints that need an exact payload, capture a
+single allowlisted endpoint with a JSON body file. hscli stores a redacted
+`<endpoint>.request.json` proof file and a request-body SHA-256 in the manifest:
+
+```bash
+hscli --profile source-readonly --json internal capture \
+  --surface permission-access \
+  --endpoint app-users-batch \
+  --portal-id "$PORTAL_ID" \
+  --cookie-file "$HUBSPOT_COOKIE_FILE" \
+  --body-file app-users-batch=./bodies/app-users-batch.json \
+  --out-dir "$HOME/client-migration-assets/portal-$PORTAL_ID-full-backup/internal-api/permission-access"
+```
+
+Migration/setup adapters stay explicit instead of becoming a generic internal
+API passthrough. The capture allowlist is versioned in
+`src/commands/internal/catalog.ts`; write-like internal adapters stay named,
+auditable, and guarded by `--force`, while generic POST capture remains limited
+to read-like HubSpot operations such as search, preview, batch hydration,
+async resolve, or Chirp RPC reads:
+
+```bash
+hscli settings business-units capture --portal-id 12345 --cookie-file ./session.cookie
+hscli settings business-units create-internal --portal-id 12345 --data '{"name":"Example Business Unit"}' --skip-existing
+hscli settings permission-sets roles list --portal-id 12345 --cookie-file ./session.cookie
+hscli settings permission-sets assignments list --portal-id 12345 --cookie-file ./session.cookie
+hscli settings flp property 0-1 email --portal-id 12345 --cookie-file ./session.cookie
+hscli settings permission-sets users assign user-1 --portal-id 12345 --permission-set-id 70 --cookie-file ./session.cookie --force
+hscli settings permission-sets users assign user-1 --portal-id 12345 --permission-set-ids 70,71 --cookie-file ./session.cookie --force
+hscli settings permission-sets users assign-batch --portal-id 12345 --data '{"assignments":[{"userId":"user-1","permissionSetIds":["70","71"]}]}' --cookie-file ./session.cookie --force
+hscli settings users create --data '{"email":"user@example.com"}'  # invite email suppressed by default
+```
+
+Browser-session adapters only send cookies to allowlisted HubSpot app hosts
+(`app.hubspot.com`, `app-eu1.hubspot.com`, etc.). Netscape/JSON cookie exports
+are filtered to the selected HubSpot domain before the request is made.
+
 ## Write safely
 
 ```bash
@@ -74,10 +264,15 @@ hscli crm contacts create --data '{"properties":{"email":"jane@acme.com"}}'
 # Preview what the call would look like
 hscli --dry-run crm contacts create --data '{"properties":{"email":"jane@acme.com"}}'
 
-# Execute — with an Idempotency-Key baked in automatically
+# Execute — with an operation correlation key generated automatically
 hscli --force crm contacts create --data '{"properties":{"email":"jane@acme.com"}}'
 ```
 
+hscli reuses the same correlation key across retries and honors native
+idempotency semantics on endpoints that support them. It never assumes every
+HubSpot mutation is replay-safe; deterministic action contracts and read-only
+verification are the stronger boundary for approved agent writes.
+
 Policy file + change-ticket enforcement for ops teams:
 
 ```bash
@@ -90,7 +285,10 @@ hscli --force --policy-file ./policy.json --change-ticket CHG-123 \
 Drop `hscli` into any MCP client — Claude Desktop, Cursor, Claude Code, or your own agent runtime.
 
 ```bash
-hscli mcp
+hscli mcp                       # 29 essential read tools (default)
+hscli mcp --surface crm         # curated CRM read/write tools
+hscli mcp --surface migration   # curated cross-product migration tools
+hscli mcp --surface full        # all 180 tools, including raw API
 ```
 
 For Claude Desktop, add to `claude_desktop_config.json`:
@@ -100,19 +298,23 @@ For Claude Desktop, add to `claude_desktop_config.json`:
   "mcpServers": {
     "hscli": {
       "command": "hscli",
-      "args": ["mcp"],
+      "args": ["mcp", "--surface", "minimal"],
       "env": { "HSCLI_MCP_PROFILE": "default" }
     }
   }
 }
 ```
 
-The MCP server exposes three tool families:
+The MCP server exposes three tool families across explicit surfaces:
 
 - **Per-object tools** — `crm_contacts_list`, `crm_deals_create`, `crm_custom_records_search`, …
 - **HubSpot Remote MCP compat** — same tool names as `mcp.hubspot.com` (`search_crm_objects`, `manage_crm_objects`, …) so agents built for HubSpot's hosted MCP drop in without changes
 - **Extension surface** — workflows, files, forms, webhooks, HubDB, conversations, and more, all with the same `--force` + policy gates as the CLI
 
+`minimal` is intentionally the default so an agent does not pay the context
+and security cost of 180 tools for a simple CRM read. The raw `hub_api_request`
+tool exists only in `full`. See the generated [tool catalog](docs/MCP_TOOL_CATALOG.md).
+
 Every MCP tool call goes through the same safety rails as the CLI. Token redaction is enforced on every response. `HSCLI_MCP_PROFILE` locks the stdio server to one auth profile to prevent cross-tenant access.
 
 ## Observability
@@ -147,7 +349,9 @@ Every request hscli makes is append-only JSONL. Pair `trace` with `audit` for fu
 - **Legacy v1/v2** — every pre-v3 surface preserved for portals that still need them
 - **Raw API** command with path-scope controls + full OAuth flow support
 
-Enterprise defaults: `--dry-run`, `--force`, policy files, change tickets, capability probing, shared rate-limit enforcement, token redaction, path scope allowlisting, idempotency keys on every write.
+Enterprise defaults: `--dry-run`, `--force`, policy files, change tickets,
+capability probing, shared rate-limit enforcement, token redaction, path scope
+allowlisting, endpoint-aware retries, and correlation keys on writes.
 
 </details>
 
@@ -177,19 +381,27 @@ Exact endpoint → tier mapping in [docs/TIERS.md](docs/TIERS.md).
 ## Design principles
 
 1. **CLI-first, MCP as a peer.** Every MCP tool has a matching `hscli` command — same write gates, same redaction, same capability probing in both.
-2. **Self-hosted, token-sovereign.** Your HubSpot private app token stays on your machine. No telemetry, no phone-home.
-3. **Safe by default.** Mutations are blocked unless `--force` is explicit. `--dry-run` previews every write. Idempotency-Key on every mutation.
-4. **HubSpot-native.** Reads `X-HubSpot-RateLimit-*` headers, throttles proactively across clients, stops on daily hard-limit exhaustion, caches capabilities by `portalId + scopes`, validates payloads offline.
+2. **Agent-safe operator layer.** Deterministic context, plans, reports, traces, and policy checks happen before AI writes or summaries.
+3. **Self-hosted, token-sovereign.** Your HubSpot private app token stays on your machine. No telemetry, no phone-home.
+4. **Safe by default.** Mutations are blocked unless `--force` is explicit. `--dry-run` previews every write. Approved actions bind exact arguments to verification steps; endpoint-aware retries reuse one correlation key.
+5. **Multi-portal explicitness.** Every plan and command keeps `--profile` visible so source, sandbox, and production portals cannot blur together.
+6. **HubSpot-native.** Reads `X-HubSpot-RateLimit-*` headers, throttles proactively across clients, stops on daily hard-limit exhaustion, caches capabilities by `portalId + scopes`, validates payloads offline.
 
 ## Output modes
 
 ```bash
 hscli --json crm companies list --limit 3          # JSON envelope
+hscli --format jsonl crm contacts list --limit 100 # one compact envelope per result
 hscli --format csv crm contacts list --limit 5     # CSV
 hscli --format yaml crm deals get 123              # YAML
 hscli --format table crm contacts list --limit 5   # table (default)
 ```
 
+`jsonl` is the streaming format for agents and shell pipelines. Top-level
+arrays and HubSpot `results` pages produce one redacted JSON envelope per
+record; page metadata is repeated under `meta` so each line remains
+self-describing.
+
 ## Terminal session
 
 The HubSpot-UI recording at the top shows the *outcome*. Here's the *cause* — the same fixture built and torn down entirely from the shell:
@@ -217,6 +429,7 @@ Under `HSCLI_HOME` (default: `~/.revfleet`):
 - [docs/MCP.md](docs/MCP.md) — MCP server tool catalog
 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) · [docs/SAFETY_MODEL.md](docs/SAFETY_MODEL.md) · [docs/WHY_HOW_WHAT.md](docs/WHY_HOW_WHAT.md)
 - [docs/ROADMAP-DATE-BASED-API.md](docs/ROADMAP-DATE-BASED-API.md) — HubSpot's `/YYYY-MM/` migration plan
+- [docs/PORTAL_BACKUP.md](docs/PORTAL_BACKUP.md) — full-portal downgrade/migration backup runbook
 - [docs/PLUGIN_GUIDE.md](docs/PLUGIN_GUIDE.md) — writing plugins
 - [docs/COOKBOOK.md](docs/COOKBOOK.md) — recipes
 - [docs/PUBLISHING.md](docs/PUBLISHING.md) — release runbook (maintainers)

package/dist/cli.js

@@ -20,6 +20,7 @@ import { registerAudit } from "./commands/audit/index.js";
 import { registerLists } from "./commands/lists/index.js";
 import { registerSales } from "./commands/sales/index.js";
 import { registerReporting } from "./commands/reporting/index.js";
+import { registerReports } from "./commands/reports/index.js";
 import { registerExports } from "./commands/exports/index.js";
 import { registerSiteSearch } from "./commands/site-search/index.js";
 import { registerTimeline } from "./commands/timeline/index.js";
@@ -33,10 +34,22 @@ import { registerEmailEvents } from "./commands/email-events/index.js";
 import { registerMediaBridge } from "./commands/media-bridge/index.js";
 import { registerFeatureFlags } from "./commands/feature-flags/index.js";
 import { registerGuide } from "./commands/guide/index.js";
+import { registerAgent } from "./commands/agent/index.js";
+import { registerContext } from "./commands/context/index.js";
+import { registerPortals } from "./commands/portals/index.js";
+import { registerBackup } from "./commands/backup/index.js";
+import { registerSalesContent } from "./commands/sales-content/index.js";
+import { registerSequencesInternal } from "./commands/sequences/index.js";
+import { registerSalesTemplates } from "./commands/sales-templates/index.js";
+import { registerPlaybooks } from "./commands/playbooks/index.js";
+import { registerContentPermissions } from "./commands/content-permissions/index.js";
+import { registerUi } from "./commands/ui/index.js";
 import { registerMarketingEmailsV1 } from "./commands/marketing-emails-v1/index.js";
+import { registerEmailTracking } from "./commands/email-tracking/index.js";
 import { registerIntegrators } from "./commands/integrators/index.js";
 import { registerIntegrations } from "./commands/integrations/index.js";
 import { registerExtensions } from "./commands/extensions/index.js";
+import { registerInternal } from "./commands/internal/index.js";
 import { registerBroadcast, registerVisitorIdentification, registerSubmissions, registerScheduler, registerTax, registerAppinstalls, registerMarketingExtras, registerOwnersExtras, registerBusinessUnits, registerBroadcastsRoot, registerFormIntegrations, } from "./commands/legacy/index.js";
 import { registerContactsV1, registerCompaniesV2, registerDealsV1, registerOwnersV2, registerEngagementsV1, registerPropertiesLegacy, registerReportsV2, registerPaymentsSubscriptions, registerContentV2, registerSalesExtensions, registerComments, registerCallingV1, registerChannels, } from "./commands/legacy-v1/index.js";
 import { CliError, printError } from "./core/output.js";
@@ -59,7 +72,7 @@ export function createProgram() {
         .version(pkg.version)
         .option("--profile <name>", "Auth profile", "default")
         .option("--json", "JSON output")
-        .option("--format <mode>", "Output format: json|table|csv|yaml")
+        .option("--format <mode>", "Output format: json|jsonl|table|csv|yaml")
         .option("--dry-run", "Simulate writes")
         .option("--force", "Confirm write operations")
         .option("--strict-capabilities", "Fail fast when endpoint capability status is unknown")
@@ -125,6 +138,7 @@ export function createProgram() {
     registerLists(program, () => ctx);
     registerSales(program, () => ctx);
     registerReporting(program, () => ctx);
+    registerReports(program, () => ctx);
     registerExports(program, () => ctx);
     registerSiteSearch(program, () => ctx);
     registerTimeline(program, () => ctx);
@@ -137,11 +151,23 @@ export function createProgram() {
     registerEmailEvents(program, () => ctx);
     registerMediaBridge(program, () => ctx);
     registerFeatureFlags(program, () => ctx);
+    registerUi(program, () => ctx);
     registerGuide(program, () => ctx);
+    registerAgent(program, () => ctx);
+    registerContext(program, () => ctx);
+    registerPortals(program, () => ctx);
+    registerBackup(program, () => ctx);
+    registerSalesContent(program, () => ctx);
+    registerSequencesInternal(program, () => ctx);
+    registerSalesTemplates(program, () => ctx);
+    registerPlaybooks(program, () => ctx);
+    registerContentPermissions(program, () => ctx);
     registerMarketingEmailsV1(program, () => ctx);
+    registerEmailTracking(program, () => ctx);
     registerIntegrators(program, () => ctx);
     registerIntegrations(program, () => ctx);
     registerExtensions(program, () => ctx);
+    registerInternal(program, () => ctx);
     registerBroadcast(program, () => ctx);
     registerVisitorIdentification(program, () => ctx);
     registerSubmissions(program, () => ctx);
@@ -241,9 +267,9 @@ function resolveApiBaseUrlOverride(hublet, rawApiBaseUrl) {
 function resolveOutputFormat(raw, jsonFlag) {
     const fallback = "table";
     const value = (raw === undefined || raw === null) ? fallback : String(raw).trim().toLowerCase();
-    const allowed = new Set(["json", "table", "csv", "yaml"]);
+    const allowed = new Set(["json", "jsonl", "table", "csv", "yaml"]);
     if (!allowed.has(value)) {
-        throw new CliError("INVALID_FORMAT", "format must be one of: json, table, csv, yaml");
+        throw new CliError("INVALID_FORMAT", "format must be one of: json, jsonl, table, csv, yaml");
     }
     if (jsonFlag && value !== "json" && raw !== undefined && raw !== null) {
         throw new CliError("INVALID_FORMAT", "--json cannot be combined with --format != json");