connect-hubspot-agent-cli

Files (1)

• SKILL.md

SKILL.md (first lines)

# Connect Claude Code to HubSpot via the Agent CLI

HubSpot's Agent CLI is a command-line tool built for AI agents. Where the MCP server is for looking things up in conversation, the CLI is for doing administrative work: it reads and writes in bulk, deletes, manages properties and pipelines, and creates workflows. It is the most direct connection between Claude Code and a portal.

## Why This Matters

Before the CLI, any HubSpot job that was too big for MCP needed a purpose-written script. That is still the right answer for work you repeat and need to audit. For the long tail of one-off administrative jobs (archive these 60 properties, re-label this association, upsert this file) a script is overhead, and the CLI fills the gap.

**It is beta.** HubSpot states that commands, flags, and behavior may change without notice. Treat it as a power tool for supervised sessions, not as a dependency for anything scheduled.

## Where It Fits

| | Agent CLI (this skill) | Remote MCP (`/connect-hubspot-mcp`) | REST scripts (scripted skills) |
|---|---|---|---|
| Status | Beta | Generally available | v3/v4 paths |
| Delete and archive | Yes, guarded | No | Yes, guarded |
| Workflows | List, get, create, update, delete | No | Create, export, restore |
| Bulk input | JSONL on stdin | A few records at a time | Batches of 100 |
| Audit trail | Local `history` log of destructive operations | None | CSV export before every mutation |
| Abort threshold | None built in | Not applicable | Hard-coded per skill |
| Use it for | One-off bulk and admin jobs, supervised | Lookups and spot-checks | Anything repeatable or destructive at scale |

When a scripted skill exists for the job, prefer the skill. It was written with a threshold, an export, and a rollback note for that specific operation. Use the CLI when no skill covers the job, and apply the safe-use rules below yourself.

## Prerequisites

- Claude Code, with permission to run shell commands
- A HubSpot user whose permissions cover the work. The CLI is available on all HubSpot plans
- Approval from a Super Admin if the portal restricts who can connect apps
- On Claude Team or Enterprise, an admin may need to allowlist `api.hubapi.com`

## Execution Pattern

### Stage 1: Plan

Decide which mode you need before installing:

| Mode | How | Acts as | Use when |
|------|-----|---------|----------|
| User | `hubspot auth login` | You, with your HubSpot permissions | Almost always |
| Admin | `HUBSPOT_ACCESS_TOKEN` set to a service key | The service key's scopes | Schema changes, association batch operations, and other calls that need account-level access |

Start in user mode. It cannot exceed what you could do by hand in the UI.

### Stage 2: Execute

1. **Install.** Read the script before running it, as with any `curl | sh`:

   ```bash
   curl -fsSL https://api.hubapi.com/hub/cli/backend/hub-cli/latest/install.sh | sh
   ```

   On Windows PowerShell: `irm https://api.hubapi.com/hub/cli/backend/hub-cli/latest/install.ps1 | iex`

   The binary is `hubspot`. It is separate from `hs`, HubSpot's developer CLI for building apps and CMS projects.

2. **Verify and sign in.**

   ```bash
   hubspot --version
   ```

   ```bash
   hubspot auth login
   ```

   The login opens a browser. Review the requested permissions and connect.

3. **Confirm which portal you are in.**

   ```bash
   hubspot whoami
   ```

   Read the account name and ID back to the user and wait for them to confirm it is the intended portal. This matters most for anyone with access to more than one account.

4. **Optionally install HubSpot's own skills** for the CLI. They teach an agent the command surface and are complementary to this toolkit:

   ```bash
   npx skills add hubspot/agent-cli-skills
   ```

**Admin mode**, only when a command needs it: put a service key in the environment for that session and remove it afterward.

```bash
export HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxxxx
```

```bash
unset HUBSPOT_ACCESS_TOKEN
```

This is the same variable this repo's scripts read from `.env`. If it is exported in your shell, the CLI silently runs in admin mode. Check `hubspot whoami` before any write.

### Stage 3: After

Run a read and confirm the output matches the portal:

```bash
hubspot owners list --format table
```

The owner names should be people the user recognizes. If they are not, you are in the wrong account: stop and sign in again.

Before the first real write, run that command with `--dry-run` and read the preview together with the user, so the guard rails are familiar before they are needed.

## Command Surface

| Group | Subcommands |
|-------|-------------|
| `objects` | `types`, `list`, `get`, `search`, `create`, `update`, `upsert`, `merge`, `delete` |
| `properties` | `list`, `get`, `create`, `update`, `delete`, `batch-read`, `batch-create`, `batch-archive` |
| `pipelines` | `list`, `get`, `create`, `update`, `delete`, plus `stages` variants |
| `associations` | `list`, `create`, `delete`, batch variants, labels, limits |
| `workflows` | `list`, `get`, `create`, `update`, `delete` |
| `segments` (alias `lists`) | Segment and list management |
| `schemas` | `list`, `get`, `create`, `update`, `delete` |
| `owners` | `list` |
| `views`, `reports`, `imports`, `query`, `sequences`, `marketing`, `conversations`, `analytics`, `buyer-intent` | See `hubspot help` |

From TomGranot/hubspot-admin-skills, MIT.

More from TomGranot/hubspot-admin-skills