HubSpot Agent CLI: The Operator's Guide

The HubSpot Agent CLI is a command line tool that connects AI coding agents, like Claude Code, Claude Cowork, and OpenAI Codex, to your HubSpot account so they can work with your CRM data directly. It is in public beta as of June 2026, ships with every HubSpot plan, and uses no HubSpot Credits. It is built for repetitive, bulk, and scheduled work, not live chat.

What is the HubSpot Agent CLI?

It is HubSpot's way of letting the AI agents you already use do real work inside your portal. Instead of an agent just answering questions about your CRM, it can read records, run searches, create and update objects, manage pipelines, properties, and associations, build workflows and reports, and pull activity history, all through one command line tool that speaks the format agents handle best.

Two things trip people up on day one. First, this is not the HubSpot CLI developers use to build themes and apps; the Agent CLI is a separate binary with its own command surface, built for agents to operate rather than for humans to type. Second, it does not replace the HubSpot connectors for ChatGPT and Claude or the MCP server. Those handle live conversation. The Agent CLI handles the work that should run without you: the Monday morning pipeline sweep, the bulk cleanup, the scheduled report.

It entered public beta on June 23, 2026, and HubSpot is shipping changes to it fast. Commands and behavior can still move under your feet, which is exactly why the guardrails below matter.

How does the HubSpot Agent CLI work?

Setup takes minutes. You paste a one-paragraph install prompt from HubSpot into your agent workspace; the agent installs the CLI, runs hubspot auth login to open a browser sign-in, and adds HubSpot's skill library, which teaches the agent how to handle CRM searches, bulk operations, data quality work, workflows, and reporting.

From there, the mechanics that matter to an operator:

• It acts as you. The default OAuth login is scoped to your HubSpot user permissions, the same access you have in the UI. What you can touch, the agent can touch.
• Commands read like plain English. The pattern is hubspot noun verb: objects search, pipelines list, workflows create, reports fetch-dataset. Your agent chains them together with standard pipes for bulk work.
• Every write can be previewed. A dry-run flag shows what would change before anything changes, and truly destructive commands, like deleting a pipeline, require a safety digest from a dry run before they will execute at all.
• There is a paper trail. A local history command logs every destructive operation the CLI has run.
• Admin mode exists, and it is sharp. Some operations (custom object schemas, most deletes) need a service key token instead of OAuth. That token carries account-level power and no per-user audit trail. Treat it accordingly.

Agents can also work with revenue records, such as invoices, quotes, payments, and subscriptions, read-only, through a separate opt-in beta a Super Admin has to switch on.

How is it different from the MCP server and AI connectors?

HubSpot now has three front doors for AI, and they are complements, not competitors. Here is the honest split:

For agent workloads the CLI is also cheaper to run: no tool schemas loaded into the agent's context and no protocol overhead per call, which adds up fast on bulk jobs.

What does the Agent CLI do for your business?

It turns the recurring ops work nobody has time for into work that happens before you sit down. The pattern that works: an agent runs on a schedule, does the reading, and hands a human a plan. Pipeline reviews that flag closing deals with no recent activity. Data quality sweeps that find duplicates and missing fields, then preview the fix before applying it. Meeting prep that pulls deal, ticket, and email history into one summary. Call transcript analysis across a whole quarter.

Our take: this is the most useful thing HubSpot has shipped for RevOps teams this year, and the risk is exactly proportional to how casually you connect it. The same tool that fixes a thousand records can delete a thousand records, with your name on the change.

Who it is NOT for, honestly:

• Teams where nobody will supervise the agent. It runs with a real user's permissions, including deletes. Unattended plus unsupervised is how CRMs get wrecked.
• Anyone who wants a chat experience. If you are asking questions and acting on answers in real time, the connectors and MCP server are the right tools.
• Teams that do not use an AI coding agent yet. The CLI is the bridge, not the agent; without Claude Code, Cowork, Codex, or similar, there is nothing to connect.
• Production-critical automations you cannot afford to revisit. It is a beta; commands and behavior can change without notice.

If you are weighing this against HubSpot's own prebuilt agents, they solve different problems: the Agent CLI powers your agents on your schedule, while something like the Breeze Prospecting Agent is a finished agent HubSpot runs for you.

How Hubjoy runs AI agents on HubSpot portals

We run AI agents against HubSpot every day in our own operation, and every write still goes through a human. That experience is baked into the order we follow before an Agent CLI connection touches a client portal:

1. Governance before connection. Turn on HubSpot's App Governance beta and decide who is allowed to connect the CLI before the first login, not after. Without it, anyone with a login can wire an agent into your CRM.
2. A dedicated user, not a Super Admin. Connect with a user whose permissions match the job. The agent inherits whatever that user can do, so a Super Admin connection hands it the keys to everything.
3. Read-only for the first two weeks. Reports, summaries, audits. The agent earns write access by being right about what it reads.
4. Dry-run everything, save the plan. Every mutation gets previewed, written to a plan file, and reviewed by a person before it is applied. The CLI is built for exactly this loop; use it.
5. Name what agents create. Agent-built workflows, properties, and pipelines get a prefix and a weekly audit. Structural duplicates creep in quietly when several agents or people prompt the same portal.
6. Sandbox for structural change. Schema, pipeline, and workflow changes rehearse in a sandbox account before they run in production. HubSpot's own beta docs say the same thing; almost nobody does it.

The gotcha we watch for: the service-key shortcut. An operation fails under OAuth, someone pastes an account-level service key to make the error go away, and now the agent runs with broad permissions and no per-user audit trail. When OAuth blocks something, that is a decision point for an admin, not a workaround.

Frequently asked questions

How much does the HubSpot Agent CLI cost?

Nothing on the HubSpot side during the public beta: no HubSpot Credits, no separate fee, and it is included with every plan. The real cost is the AI agent you attach, meaning your Claude or OpenAI subscription and its usage. As with any beta, pricing could change when it reaches general availability.

Which HubSpot plans include the Agent CLI?

All products and plans, including free tools, per HubSpot's documentation. You need a HubSpot user login to authenticate, and Super Admins can control who is allowed to connect it through HubSpot's App Governance beta.

What can AI agents actually do with the Agent CLI?

Read, search, create, update, merge, and delete CRM records (contacts, companies, deals, tickets, and custom objects), manage pipelines and stages, properties, associations, saved views, and workflows, build reports from CRM SQL queries, and pull activity history including call transcripts and email threads. Revenue records like invoices and quotes are available read-only through an opt-in beta. Everything runs within the permissions of the connected HubSpot user.

Is it safe to let an AI agent change my CRM?

It can be, if you use the guardrails. The CLI acts within the connected user's permissions, every write supports a dry-run preview, destructive commands require a safety digest before executing, and a local history log records destructive operations. HubSpot's own beta docs warn that write operations can permanently delete live data, so start read-only, review every plan before applying it, and rehearse structural changes in a sandbox.

How is the Agent CLI different from the HubSpot MCP server or the ChatGPT and Claude connectors?

The connectors and the MCP server are built for live conversation: you ask, the AI answers, you act. The Agent CLI is built for the opposite case: repetitive, bulk, and scheduled work that runs in the background without a human in the loop for every step. HubSpot positions them as complements, and in practice most teams end up using both.

Which AI agents does it work with?

HubSpot names Claude Code, Claude Cowork, and OpenAI Codex, and says other compatible AI coding agents work too. One setup note: on Claude Team or Enterprise accounts, a Claude admin must allowlist api.hubapi.com in the network egress settings before the CLI can install or run.

Is the HubSpot Agent CLI generally available?

No. It entered public beta on June 23, 2026 after a private beta announced in May 2026. Beta terms apply, and HubSpot notes that commands, flags, and behavior may change without notice. We will update this page when it reaches general availability.

Thinking about wiring an agent into your portal?

We will tell you whether your CRM is clean enough to automate against, and what to fix first if it is not. Thirty minutes, no pitch.

Book your free HubSpot Review