JSPM

Your HubSpot portal, in one binary.

_{↳ Live tour · terminal writes, HubSpot reflects · ~60s on a real portal.}

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.

No SaaS middleman, no proprietary dashboard, no "download the CLI, then also install the desktop app". Just a CLI that respects production.

Install & auth

npm install -g @revfleet/hscli
printf '%s' 'pat-eu1-XXXX-XXXX-XXXX' | hscli auth login --token-stdin
hscli crm contacts list --limit 5

Create a Private App token at Settings → Integrations → Private Apps → Create private app in your HubSpot portal.

Write safely

# 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 Idempotency-Key baked in automatically
hscli --force crm contacts create --data '{"properties":{"email":"jane@acme.com"}}'

Policy file + change-ticket enforcement for ops teams:

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.

hscli mcp

For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "hscli": {
      "command": "hscli",
      "args": ["mcp"],
      "env": { "HSCLI_MCP_PROFILE": "default" }
    }
  }
}

The MCP server exposes three tool families:

• 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

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

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

What "1,180 endpoints" means

Every one of HubSpot's documented public API endpoints has a corresponding CLI subcommand — verified against an automated scrape of HubSpot's developer documentation.

It does not mean every endpoint returns 2xx on your portal. HubSpot tier-locks hundreds of endpoints behind paid plans:

Exact endpoint → tier mapping in 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, caches capabilities by portalId + scopes, validates payloads offline.

Output modes

hscli --json crm companies list --limit 3          # JSON envelope
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)

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:

Source script · recording config · how the recordings are made

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 — full command surface
• docs/COMPARISON.md — MCP tool families, CLI groups, coverage, safety, observability
• docs/MCP.md — MCP server tool catalog
• docs/ARCHITECTURE.md · docs/SAFETY_MODEL.md · docs/WHY_HOW_WHAT.md
• docs/ROADMAP-DATE-BASED-API.md — HubSpot's /YYYY-MM/ migration plan
• docs/PLUGIN_GUIDE.md — writing plugins
• docs/COOKBOOK.md — recipes
• docs/PUBLISHING.md — release runbook (maintainers)
• CONTRIBUTING.md · SECURITY.md · CHANGELOG.md

Domain setup guides: PORTAL · CMS · Commerce · Marketing · Sales · Service · Operations · Reporting · Integrations & Notifications

Tutorials: secure agent writes · audit portal writes · trace + replay

Contributing

Issues and PRs welcome — see CONTRIBUTING.md for the workflow, coding standards, and live-portal contract tests.

License

MIT — see LICENSE.