hscli

<p align="center"> <img src="brand/readme-hero.svg" alt="hscli — agentic HubSpot CLI + MCP server" width="100%"> </p> <p align="center"> <strong>The agent-safe HubSpot operator.</strong> </p> <p align="center"> <a href="https://www.npmjs.com/package/@revfleet/hscli"><img src="https://img.shields.io/npm/v/@revfleet/hscli.svg?style=flat-square&color=22D3EE&labelColor=0F172A" alt="npm"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22D3EE?style=flat-square&labelColor=0F172A" alt="MIT"></a> <a href="docs/TIERS.md"><img src="https://img.shields.io/badge/HubSpot%20API-1%2C180%20endpoints-22D3EE?style=flat-square&labelColor=0F172A" alt="1,180 HubSpot endpoints"></a> </p> <p align="center"> <img src="https://raw.githubusercontent.com/revfleet/hscli/main/docs/demo-hubspot.gif" alt="hscli writing into a HubSpot portal in real time — records appear in the UI as hscli creates them" width="100%"> </p> <p align="center"> _{↳ Live tour · terminal writes, HubSpot reflects · ~60s on a real portal.} </p> --- ## Why `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 npm install -g @revfleet/hscli hscli auth login --profile client-readonly hscli auth set-mode client-readonly read-only hscli --profile client-readonly ``` Running `hscli` with no command opens the guided operator home. It shows the active portal, safety posture, the latest baseline, and one recommended next step. Use `hscli --help` when you want the full command reference. In an interactive terminal, `auth login` opens a hidden terminal prompt, so the Private App token never appears in shell history or terminal output. In CI or a non-interactive shell, pass it through stdin instead: ```bash printf '%s' "$HUBSPOT_PRIVATE_APP_TOKEN" | hscli auth login --profile client-readonly --token-stdin ``` Create a Private App token at **Settings → Integrations → Private Apps → Create private app** in your HubSpot portal. For EU/AP/NA hublet routing, hscli auto-detects from token/account metadata. You can also pin it explicitly: ```bash hscli auth login --profile live --hublet eu1 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. Missing scopes become explicit coverage gaps instead of stopping the run: ```bash hscli --profile client-readonly baseline \ --output ./evidence/portal-baseline ``` Open `portal-baseline.md` for the human report. Use `revfleet-evidence.json` as the SHA-256 integrity-checked, aggregate-only machine contract. The same directory keeps the deeper audit trail: `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 locally. The Markdown report is rendered only from the allowlisted aggregate contract, not from raw step files. It cannot reintroduce CRM records, user identities, team names, workflow names, scopes, or tokens. Use `--fail-fast` only when a missing signal should stop the baseline instead of remaining an explicit gap. Regenerate the human report from an existing completed run without calling HubSpot again: ```bash hscli agent evidence report ./evidence/portal-baseline ``` Turn that local bundle into a SHA-256 integrity-checked, aggregate-only RevFleet evidence contract without uploading raw steps, CRM records, user identities, or tokens. The one-command opt-in keeps the full local bundle and submits only its aggregate contract after the baseline completes: ```bash export REVFLEET_API_KEY="<scan:run key from RevFleet>" export REVFLEET_BACKEND_URL="https://your-revfleet-origin.example" hscli --profile client-readonly baseline \ --output ./evidence/portal-baseline \ --submit ``` `--submit` is explicit: hscli always writes the local evidence and report first, then sends only the aggregate contract. A submission error leaves those local artifacts intact for inspection or a later retry. `--backend-url <origin>` overrides `REVFLEET_BACKEND_URL`; `--api-key-env <name>` overrides the key variable. hscli has no hidden hosted default: the destination must be explicit and remote origins must use HTTPS. For an already completed baseline, use the same bridge without rerunning any HubSpot reads: ```bash hscli agent evidence export ./evidence/portal-baseline \ --output ./evidence/revfleet-evidence.json hscli agent evidence submit ./evidence/portal-baseline ``` The exported `revfleet.hscli-evidence/v1` document declares coverage for every baseline signal and carries a deterministic SHA-256 digest. A missing or failed signal remains `missing` or `failed`; it is never converted into a bad portal score. RevFleet stores this evidence separately from the complete 53-check extension scan. ## Operator workflows Start from intent instead of memorizing the whole command tree: ```bash hscli ui # terminal home: baseline status, profiles, safety, next action hscli baseline # one-command read-only baseline + Markdown + integrity-checked JSON 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 ``` For an authenticated portal that has not been audited yet, `hscli ui` recommends the profile-scoped baseline first. It then remembers the latest default-path run for that profile, shows its coverage and report path, and moves the operator to RevFleet evidence submission when `REVFLEET_BACKEND_URL` and `REVFLEET_API_KEY` are configured. The credential value is never rendered. Without that explicit bridge, the next action remains policy and trace guardrails. 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 evidence export ./evidence/portal-baseline --output ./evidence/revfleet-evidence.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 # Blocked — writes need explicit intent hscli crm contacts create --data '{"properties":{"email":"jane@acme.com"}}' # → WRITE_CONFIRMATION_REQUIRED # Preview what the call would look like hscli --dry-run crm contacts create --data '{"properties":{"email":"jane@acme.com"}}' # 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 hscli --force --policy-file ./policy.json --change-ticket CHG-123 \ crm contacts delete 123 ``` ## Run as an MCP server Drop `hscli` into any MCP client — Claude Desktop, Cursor, Claude Code, or your own agent runtime. ```bash 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`: ```json { "mcpServers": { "hscli": { "command": "hscli", "args": ["mcp", "--surface", "minimal"], "env": { "HSCLI_MCP_PROFILE": "default" } } } } ``` 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 ```bash hscli trace start # start recording every request hscli --force crm contacts create … # → appends to the trace JSONL hscli trace stop hscli trace stats ./trace-*.jsonl # p50/p95/p99 latency, method breakdown hscli trace diff ./run-a.jsonl ./run-b.jsonl # spot reproducibility drift hscli audit writes --since 24h # who wrote what, when hscli audit by-tool # per-MCP-tool call count + error rate ``` Every request hscli makes is append-only JSONL. Pair `trace` with `audit` for full "who did what when" provenance — no extra infrastructure required. ## What's in the box <details> <summary><strong>Surface coverage</strong> — click to expand</summary> - **CRM** — contacts, companies, deals, tickets, leads, quotes, products, line items, orders, carts, discounts, fees, taxes, invoices, subscriptions, payments, goals, communications, users, custom objects, properties, pipelines, associations v4, owners, imports, exports, engagements, sync, describe/validate, timeline, CRM Cards - **Marketing** — emails (v3 + legacy v1), campaigns, ads, social, SEO, landing pages, transactional, subscriptions, events, behavioral events, forms - **Sales** — sequences, meetings, calling, scheduler, sales extensions - **Service** — conversations, feedback, chatflows, knowledge-base, ticket pipelines, visitor-identification - **CMS** — site/landing/blog pages, HubDB, URL redirects, source-code, domains, SEO audit - **Settings** — users, teams, business units, currencies, GDPR, audit-logs, communication preferences - **Operations** — lists, reporting, exports, workflows (v4 + legacy), automation, webhooks, timeline - **Commerce Hub** — quotes, products, line-items, invoices, subscriptions, payments, orders, carts, taxes - **Developer Platform** — feature flags, CRM cards, integrators timeline, media bridge, extensions - **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, endpoint-aware retries, and correlation keys on writes. </details> ### What "1,180 endpoints" means hscli covers **~all** of HubSpot's documented public API endpoints — a CLI subcommand or MCP tool per endpoint, verified against an automated scrape of HubSpot's developer documentation. A small residue stays out of reach because it's UI-only, deprecated, or requires a developer-app auth model rather than a private-app bearer token; see [docs/CAPABILITY_LIBRARY.md](docs/CAPABILITY_LIBRARY.md) for the ❌/⚠️/✅ matrix. Even within the reachable set, actual 2xx responses on your portal depend on: - **Tier/plan gates** — hundreds of endpoints are locked to Marketing/Sales/Service/CMS/Ops/Commerce Pro/Enterprise or add-ons. - **Scope gates** — the private-app token must carry the right scopes; some scopes have no public endpoint surface. - **Auth-model gates** — a subset (developer-platform, app-install) require a Developer Account + `appId` + developer API key, not a bearer token. - **Deprecated surfaces** — HubDB v2, CMS performance, legacy ecommerce bridge, accounting extension, marketing calendar etc. are shipped for continuity but HubSpot may 4xx them. - **UI-only surfaces** — chatflow decision trees, SLA policies, quote e-signature, social-inbox reactions, scoring formulas and similar authoring flows have no public endpoint (covered in the library as ❌ hard-locks). HubSpot's own tier map, projected onto hscli's surface: | Portal profile | Reachable endpoints | |---|---:| | Free | ~550 / 1,180 (47%) | | Starter | ~640 / 1,180 (54%) | | Professional | ~890 / 1,180 (75%) | | Enterprise (all hubs) + Commerce + Ops | ~1,140 / 1,180 (97%) | 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. **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: <p align="center"> <img src="https://raw.githubusercontent.com/revfleet/hscli/main/docs/demo-terminal.gif" alt="hscli terminal walkthrough — blank → create → associate → read → update → archive → blank" width="100%"> </p> [Source script](https://github.com/revfleet/hscli/blob/main/scripts/demo.sh) · [recording config](https://github.com/revfleet/hscli/blob/main/scripts/demo.tape) · [how the recordings are made](https://github.com/revfleet/hscli/blob/main/scripts/README.md) ## Caches Under `HSCLI_HOME` (default: `~/.revfleet`): - `auth.json` — profile tokens (0600, in a 0700 directory) - `auth.enc` — optional encrypted vault when `HSCLI_VAULT_PASSPHRASE` is set - `capabilities.json` — portal/tier capability cache - `schema-cache.json` — CRM schema cache for describe / validate - `trace-session.json` + `trace-*.jsonl` — active trace + recorded sessions ## Documentation - [docs/COMMAND_TREE.md](docs/COMMAND_TREE.md) — full command surface - [docs/COMPARISON.md](docs/COMPARISON.md) — MCP tool families, CLI groups, coverage, safety, observability - [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) - [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) · [CHANGELOG.md](CHANGELOG.md) Domain setup guides: [PORTAL](docs/PORTAL_SETUP.md) · [CMS](docs/CMS_SETUP.md) · [Commerce](docs/COMMERCE_SETUP.md) · [Marketing](docs/MARKETING_SETUP.md) · [Sales](docs/SALES_SETUP.md) · [Service](docs/SERVICE_SETUP.md) · [Operations](docs/OPERATIONS_SETUP.md) · [Reporting](docs/REPORTING_SETUP.md) · [Integrations & Notifications](docs/INTEGRATIONS_NOTIFICATIONS_SETUP.md) Tutorials: [secure agent writes](docs/TUTORIALS/secure-agent-writes.md) · [audit portal writes](docs/TUTORIALS/audit-portal-writes.md) · [trace + replay](docs/TUTORIALS/trace-replay-repro.md) ## Contributing Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow, coding standards, and live-portal contract tests. ## License MIT — see [LICENSE](LICENSE).