Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
f1f1876
feat(api): the api group from HubSpot's 15 CRM specs, version 2026-03
leemour Nov 17, 2026
b299643
feat(crm): HubSpot as a CRM source in cli-core's shared commands; tok…
leemour Nov 17, 2026
b3c4725
chore: remove the template sample; api paces on the test clock; read-…
leemour Nov 17, 2026
d2b8477
fix(api): batch/read POSTs are reads
leemour Nov 17, 2026
a55486e
fix: review round 1 — read-only api, tested deletions and activity pa…
leemour Nov 17, 2026
dc21518
fix: review round 2 — api fails fast after a daily limit, WCHUBSPOT_A…
leemour Nov 17, 2026
253e6c4
docs(changelog): the first release's entries in a fragment
leemour Nov 17, 2026
b18ae74
fix: review round 3 — WCHUBSPOT_ACCOUNT checked against the key, lead…
leemour Nov 17, 2026
8666211
fix: review round 4 — live reads and local writes with WCHUBSPOT_TOKE…
leemour Nov 17, 2026
5eedc50
fix: review round 5 — daily-limit wait across a skipped midnight, fal…
leemour Nov 17, 2026
04fcd28
docs(setup): numbered service key steps, both menu paths, private app…
leemour Nov 17, 2026
f22e8b7
test: leave src/generated out of coverage, as notion, gcal and yandex…
leemour Nov 17, 2026
9b7043b
test: every command and option runs in a test or has a reason, as in amo
leemour Nov 17, 2026
b8ff07d
docs(readme): banner, WC-DOC-7 order, sign-in and permissions sections
leemour Nov 17, 2026
e45c62a
docs(readme): drop the not-on-npm note; this PR merges right before t…
leemour Nov 17, 2026
4f1e3f9
chore(release): live check of 0.0.0
leemour Nov 17, 2026
9480090
fix(setup): ask for scopes HubSpot has, sales-email-read for e-mails
leemour Nov 17, 2026
90a05f9
chore(release): live check of 0.0.0
leemour Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions .gitleaks.toml
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,41 @@ regex = '''(?:^|[^A-Za-z0-9/])(1//[A-Za-z0-9_-]{30,})'''
secretGroup = 1
entropy = 3.5
keywords = ["1//"]

# A HubSpot private app token or service key: `pat-`, the account's data region (any of them), a UUID (HubSpot's
# private apps guide shows `pat-na1-…`). The tests' fake is no UUID, and an all-zero first group is kept for made-up
# keys.
[[rules]]
id = "hubspot-key"
description = "HubSpot private app token or service key"
regex = '''\b(pat-[a-z]{2}\d+-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b'''
secretGroup = 1
keywords = ["pat-"]

[[rules.allowlists]]
regexes = ['''^pat-[a-z]{2}\d+-0{8}-''']

# A CRM holds its clients' phone numbers and e-mail addresses; neither may reach a fixture, a doc or a capture.
[[rules]]
id = "phone-number-e164"
description = "A phone number of a contact, a company or an owner"
regex = '''(?i)(?:phone|msisdn|number)["'\s:=]{1,10}\+?[1-9]\d{9,14}'''
tags = ["pii"]

[[rules]]
id = "email-address"
description = "An e-mail address of a contact, a company or an owner"
regex = '''\b[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}\b'''
tags = ["pii"]

[[rules.allowlists]]
regexTarget = "match"
regexes = [
# The domains RFC 2606 and RFC 6761 keep for examples, and the addresses of tools that commit here.
'''@(?:[A-Za-z0-9-]+\.)*(?:example\.(?:com|org|net)|example|test|invalid|localhost)$''',
'''@wirecat\.dev$''',
'''^noreply@anthropic\.com$''',
'''@users\.noreply\.github\.com$''',
# The example contact in HubSpot's own contacts spec, copied into the generated manifest.
'''^jon@website\.com$''',
]
258 changes: 250 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,257 @@
# hubspot
<p align="center">
<img src="https://raw.githubusercontent.com/WireCatLabs/hubspot-cli/main/docs/images/social-preview.png" alt="HubSpot CRM CLI for AI agents" width="100%">
</p>

`hubspot` is a WireCat command-line tool, started from
[cli-template](https://github.com/WireCatLabs/cli-template). Its design is in
[docs/dev/DESIGN.md](docs/dev/DESIGN.md).
# hubspot: HubSpot CRM CLI for AI agents

<p align="center">
Know where every deal stands and what changed overnight, without opening HubSpot. Ask your AI agent, and it answers
from a copy of your deals, contacts and companies on your computer, even offline.
</p>

<p align="center">
<a href="docs/index.md">Docs</a> ·
<a href="docs/usage.md">Examples</a> ·
<a href="https://discord.gg/DebENqbRrJ">Discord</a>
</p>

<p align="center">
<a href="https://github.com/WireCatLabs/hubspot-cli/actions/workflows/ci.yml"><img src="https://github.com/WireCatLabs/hubspot-cli/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://github.com/WireCatLabs/hubspot-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License: Apache 2.0"></a>
</p>

- **Ask instead of clicking.** "Which deals are stuck in Contract sent?" gets an answer in a second, in Claude Code,
Codex or any app that speaks MCP.
- **The morning starts with what changed.** `changes list` shows what each sync saw change, and a schedule sends it to
you.
- **Read only.** This release changes nothing in HubSpot. The key it signs in with needs read scopes only.

```text
You: What changed in the CRM since yesterday?
Agent: (runs hubspot work changes list "at>=1d")
· New deal "Example kitchen", 15 000 EUR, in Appointment scheduled
· "Example office" moved to Closed won, 8 200 EUR
You: Who is the contact on Example kitchen?
Agent: (runs hubspot work deals show deal:12)
Anna Example, anna@example.com, at Example LLC.
```

*Invented deals, illustrative output.*

## Quick start

A super admin of the HubSpot account makes one key first: a **service key** (Development → Keys → Service keys) or
the access token of a legacy **private app**. Give it these read scopes:

```text
crm.objects.contacts.read crm.objects.companies.read crm.objects.deals.read
crm.objects.owners.read crm.schemas.contacts.read crm.schemas.companies.read
crm.schemas.deals.read sales-email-read
```

Add `crm.objects.leads.read` on Sales Hub Professional or Enterprise to read leads, and `tickets` to read tickets
through `api`. A scope you leave out fails only the commands that need it.

```sh
npm install -g @wirecat/hubspot-cli
hubspot skill install # the agent skill, for Claude Code, Codex and Gemini CLI
hubspot work session start # paste the key when asked, it goes to the keyring
hubspot work sync # copy your deals, contacts and companies
hubspot work deals list status:open
```

`work` is a profile, a name you choose for this account. It is the first word of every command that uses the
account. You need Node.js 22.16 or a later 22.x, or Node.js 24 or later. `hubspot doctor` shows what is set up and
needs no network.

More: [install and connect](docs/installation.md)

## What you can do

- **Know the pipeline.** Open deals with their stage, amount and owner, the board of each pipeline and how many deals
stand in each stage.
- **See what changed.** Deals made, moved, won and lost, given another owner, and new activities, since any time you
name.
- **Find a client.** Any contact or company in the account, read live, with its phones and e-mails.
- **Follow the work on a deal.** Notes, calls, e-mails, meetings and tasks, copied with the deals.
- **Reach past the copy.** Every read operation of HubSpot's CRM API is a command of its own, tickets included.
- **Search across your work.** A deal turns up next to the chat where you agreed on it and the meeting where you
discussed it, if you use the other WireCat tools.

## For AI agents

Ask in plain words. The agent picks the commands.

> *"Use hubspot. Which deals are waiting in Contract sent, and for how much?"*
> *"Use hubspot. What changed in the CRM since yesterday?"*

- **Claude Code, Codex, Gemini CLI, OpenClaw** and other agents with a terminal run `hubspot` themselves.
`hubspot skill install` teaches them how.
- **Claude Desktop, Cursor** and other MCP apps connect to `hubspot work mcp serve`.

```sh
hubspot work mcp add claude-code --allow-writes # or: codex
hubspot work mcp config # the entry for Claude Desktop, Cursor and others
```

`--allow-writes` confirms you saw that the server offers commands that change something on this computer, such as
`sync` and schedules. None of them changes anything in HubSpot. Text from the account reaches the agent marked as
untrusted, so the agent reads it as data, never as instructions. The sign-in commands are not offered over MCP.

More: [agents and MCP](docs/usage.md#agents)

## Why hubspot

- **A copy of your CRM on your computer.** `sync` copies your deals with their contacts and companies, and the next
sync takes only the changes. Lists, the pipeline and search then answer with no request to HubSpot, also offline.
- **The key stays in the system keyring.** It never appears in output, errors or run records, and no command takes it
as an argument.
- **A permission on every command.** Each command and each read operation of HubSpot's API has its own level, so
you decide what an agent may read.
- **Your CRM beside your other context.** Deals sit in the same local store as your messages, notes and meetings from
the other WireCat tools, and `search all` finds them together.
- **As many accounts as you need.** Each HubSpot account is a profile you name in the command, and none is ever picked
for you.
- **Free and open source.** Apache 2.0.

## Main features

### Deals and the pipeline

```sh
hubspot work deals list stage:"Contract sent" # from the copy, offline too
hubspot work deals show deal:12 # one deal with its stage, amount and the people on it
hubspot work pipelines list # the deal pipelines and their stages
hubspot work leads list # leads, on Sales Hub Professional or Enterprise
```

### Contacts, companies and owners

```sh
hubspot work people list "Anna" # any contact in the account, read live
hubspot work organizations list "Example LLC" # any company, read live
hubspot work users list # the account's owners
```

### Activities and what changed

```sh
hubspot work activities list # notes, calls, e-mails, meetings and tasks
hubspot work changes list "at>=1d" # what changed in the last day
```

Activities are copied once you turn on the activities setting. `activities list` names the setting.

### Any read of the API

```sh
hubspot work api list # every read operation, without calling HubSpot
hubspot work api deals-list --limit 5 # one of them
```

`api` offers every read operation of HubSpot's CRM API version 2026-03, from its 15 specs, each with its own
permission. Tickets are read here.

### With your other sources

```sh
hubspot work search all "Example LLC" # the deal beside your other WireCat data
```

More: [use it](docs/usage.md) · [command reference](docs/commands.md)

### How it works

- **A key, not a user.** A service key or a private app token belongs to the account, not to a person. `hubspot`
copies the whole account, and `owner:me` names nobody: filter by `owner:<owner id>` from `users list`.
- **Polite to HubSpot.** `hubspot` sends at most 4 requests a second for each profile, under HubSpot's limits on
every plan. When the account has spent its daily allowance, it says when the allowance comes back.
- **Made for scripts.** `--json` prints one JSON value, and every error has a code to branch on.

## Sign-in and profiles

A profile is a name you choose for one HubSpot account, such as `work`. It is the first word of every command that
uses the account, and none is ever assumed: a command without one stops and names the choices.
`WCHUBSPOT_PROFILE=work` sets it for one shell session.

`hubspot work session start` asks for the key without showing it, or reads it from stdin. It checks the key against
the account and keeps it in the system keyring. `--credential-storage file` keeps it in a private file instead.
`session status --check` names the account the key reads, `session end` forgets the key on this computer, and
`session list` lists the profiles. `account remove --keep-data` or `--delete-data` forgets a profile, keeping or
deleting its copy of the CRM.

A second profile that signs in to the same HubSpot account is refused, so one copy is never synced twice.

More: [sign in](docs/installation.md#sign-in) · [profiles](docs/usage.md#the-profile-comes-first)

## Settings and permissions

Each profile has a permission level for every command and every API operation: `allow`, `ask`, `readonly` or `deny`.
A command's key is its name, such as `deals.list`. An API operation's key is `api.<command>`, such as
`api.deals-search`, and `api` covers them all.

```sh
pnpm install
pnpm build
node dist/bin/hubspot.js doctor
hubspot work config set permissions.people deny # this profile reads no contacts
```

`doctor` needs no profile. Every command that uses an account starts with one, a name you choose: `hubspot personal config show`.
Over MCP nobody is there to answer, so `ask` lets the command run. Set a key to `readonly` or `deny` to stop an
agent. `hubspot work mcp serve --permission people.list=deny` makes a key stricter for one server only, never looser.
`WCHUBSPOT_READ_ONLY=1` refuses every write.

More: [settings and permissions](docs/configuration.md#permissions)

## Limits

- `hubspot` is tested against a fake account built from HubSpot's API reference, not yet against a live account.
- Read only: no command changes deals, contacts or companies in this release, `api` included.
- Tickets are read only through `api`, not copied.
- Leads need Sales Hub Professional or Enterprise.
- Before 1.0, a minor version may change commands, `--json` fields and MCP tools. The changelog marks each such
change.

## Security

The key works like a password: anyone who has it can read what its scopes allow. `hubspot` keeps it in the system
keyring and never prints it. `hubspot` cannot revoke a key, so after a leak delete or rotate it in HubSpot.

More: [security](docs/security.md) · Report a vulnerability: [SECURITY.md](SECURITY.md)

## When something goes wrong

```sh
hubspot doctor # what is set up, without connecting
hubspot work session status --check # whether the key works, and for which account
```

More: [troubleshooting](docs/troubleshooting.md) · Ask on [Discord](https://discord.gg/DebENqbRrJ) · Bugs go to this
repository's [issues](https://github.com/WireCatLabs/hubspot-cli/issues).

## Documentation

Every page is in [docs/](docs/index.md): [install](docs/installation.md), [use it](docs/usage.md),
[commands](docs/commands.md), [settings](docs/configuration.md), [troubleshooting](docs/troubleshooting.md) and
[security](docs/security.md).

## Development

```sh
pnpm install && pnpm build
node dist/bin/hubspot.js --help
pnpm test
```

Tests run against a fake account built from HubSpot's API reference, with invented records and an injected keyring.
Nothing reaches a real account. `pnpm release:check` runs every check a release needs.

More: [testing](docs/dev/TESTING.md) · [design](docs/dev/DESIGN.md)

Pull requests, bug reports and ideas go to [issues](https://github.com/WireCatLabs/hubspot-cli/issues).

## Part of WireCat

`hubspot` is one of the [WireCat](https://wirecat.dev) tools: open-source, local-first command-line tools that give AI
agents your context from messengers, mail, calendars, documents and CRMs. Each one works on its own.

## License

[Apache 2.0](LICENSE)
22 changes: 22 additions & 0 deletions changes/feat-first-release.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
### Added

- **`session start` signs a profile in with a HubSpot service key or a private app token.** The key is read hidden or
from stdin, never as an argument, checked against the account, and kept in the keyring with the account's id. A
second profile on the same account is refused. `WCHUBSPOT_TOKEN` works in CI beside `WCHUBSPOT_ACCOUNT`, the
account's id. See [installation](../docs/installation.md).
- **`sync` copies the account's CRM into WireCat's shared store.** Deals, contacts, companies, leads (Sales Hub
Professional or Enterprise), owners, pipelines and properties, and the notes, calls, e-mails, meetings and tasks
once the activities setting is on. `deals list`, `pipelines`, `changes list` and `search all` then answer offline. A
key names no user, so every profile reads the whole copy: filter by `owner:<owner id>`, not `owner:me`.
- **`people`, `organizations` and `users` read contacts, companies and owners live from the account.**
- **`api` offers every read operation of HubSpot's CRM API, version 2026-03, from its 15 specs.** One command per
operation, each with its own permission key. This release only reads: the API's writes are not offered, and
`api show` on one says so.
- **A spent daily allowance ends the request at once and says when it comes back.** HubSpot shares one daily
allowance among every app on the account. `hubspot` reports `hubspot.daily-limit` with the wait to the account's
midnight, and stops every process on the account from asking again before then. The ten-second limit is waited
out.
- **`WCHUBSPOT_ACCOUNT` is checked against `WCHUBSPOT_TOKEN` before anything is written.** A `sync` with an id of
another account stops with `account.mismatch`, naming both ids, so one account's CRM is never filed under another's.
`session status --check` with the token alone prints the id to set. See
[troubleshooting](../docs/troubleshooting.md).
39 changes: 24 additions & 15 deletions contracts/help.snap
Original file line number Diff line number Diff line change
@@ -1,21 +1,30 @@
hubspot — a new WireCat CLI, started from cli-template
hubspot — a HubSpot account's CRM for scripts and agents, read into one local store.

Usage: hubspot <profile> <command> [options]
Account commands start with your profile, a name you choose; none is ever assumed.

What you can do:
sync copy your deals, contacts and companies; the next sync takes the changes
deals list status:open open deals with stage, amount and owner, from the store, offline
search all "kitchen" stored deals beside your other WireCat tools' data
people list "Anna" any contact, read live from the account
activities list notes, calls, e-mails, meetings and tasks on your deals
api deals-list --limit 5 any CRM read of HubSpot's API, one command per operation

Works with:
tg Telegram in the same local store: search, review and tasks offline
max MAX in the same local store: search, review and tasks offline
wa WhatsApp in the same local store: search, review and tasks offline
zm Zoom meetings: transcripts and summaries, searchable with your other WireCat data
drive Google Drive and Docs as local text, searchable with your other WireCat data
gcal Google Calendar events, searchable with your other WireCat data
memo context <person> one person across messengers, mail, notes and meetings
mail IMAP mail in the same local store: search your mailbox offline, next to your other WireCat data
b24 Bitrix24 CRM: deals, leads and pipelines, searchable with your other WireCat data
pbx Asterisk PBX calls and recordings, searchable with your other WireCat data
notion Notion pages and databases as local text, searchable with your other WireCat data
tg Telegram in the same local store: search, review and tasks offline
max MAX in the same local store: search, review and tasks offline
wa WhatsApp in the same local store: search, review and tasks offline
zm Zoom meetings: transcripts and summaries, searchable with your other WireCat data
drive Google Drive and Docs as local text, searchable with your other WireCat data
gcal Google Calendar events, searchable with your other WireCat data
memo context <person> one person across messengers, mail, notes and meetings
mail IMAP mail in the same local store: search your mailbox offline, next to your other WireCat data
b24 Bitrix24 CRM: deals, leads and pipelines, searchable with your other WireCat data
pbx Asterisk PBX calls and recordings, searchable with your other WireCat data
notion Notion pages and databases as local text, searchable with your other WireCat data

Next: hubspot commands every command, by section
hubspot help options output, offline, timeouts, dry run
For agents: hubspot skill show rules and the discovery loop
Start here: hubspot work session start (any profile name works)
Next: hubspot commands every command, by section
hubspot help options output, offline, timeouts, dry run
For agents: hubspot skill show rules and the discovery loop
Loading
Loading