The HubSpot Agent CLI is a new command-line interface purpose-built for AI agents to interact with your HubSpot CRM data — reading records, running searches, creating and updating objects, managing pipelines, properties, associations, workflows, and more. It's designed for agentic environments like Claude Cowork, Claude Code, and OpenAI Codex, and is particularly well-suited for scheduled automations, bulk operations, and background tasks that need to run without a human in the loop. The Agent CLI is now in public beta.
What's new?
The Agent CLI is a new binary, separate from the HubSpot CLI used for development. A few things worth understanding before you get started:
- It's built for agents. The Agent CLI is designed for AI agents to consume and use — not for developers to operate interactively. That said, you can run it yourself to test it or use it for custom scripting.
- It's separate from the HubSpot developer CLI. The developer CLI is for building and deploying HubSpot projects and themes. The Agent CLI has a separate command surface built for agent consumption. There's some functional overlap, but they serve different purposes and can be used together — for example, an agent could use the Agent CLI to populate mock data in a sandbox account or update production records as part of a developer-driven workflow.
- It doesn't replace the HubSpot MCP server (remote) or AI Connectors. The remote MCP server and AI Connectors remain the right choice for conversational, human-in-the-loop workflows — answering questions, pulling insights, and taking actions in real time from Claude, ChatGPT, and other chat environments. The Agent CLI complements them for the opposite scenario: repetitive, bulk, and scheduled work that runs in the background.
- For agent workflows specifically, a CLI offers practical advantages over MCP for certain use cases: CLI calls can be significantly more token-efficient (no full tool schema needs to be loaded into the agent's context window), there's no protocol negotiation overhead on each call, and commands can follow known terminal patterns — agents can filter, transform, and chain operations in a single step.
What the Agent CLI can do
Commands follow the pattern hubspot <noun> <verb>. Because the CLI is meant for agents to use, you don't need to really care about the commands themselves, but it helps to understand the capabilities. The current command surface covers:
- CRM objects: list, get, search, create, update, upsert, merge, and delete any object type (contacts, companies, deals, tickets, and custom objects), plus types to enumerate all available object types in the portal
- Pipelines: list, get, create, update, and delete pipelines and pipeline stages
- Properties: list, get, create, update, delete, and batch-manage properties across object types
- Associations: create, delete, and batch-manage associations between records, plus association label and limit management
- Owners: list HubSpot users (record owners)
- Custom object schemas: list, get, create, update, and delete schemas (requires admin mode — see below)
- Workflows: list, get, create, update, and delete workflows
- Activities: list activity history for a CRM record; fetch and delete call and meeting transcripts; list call dispositions; and fetch full email threads
- Reports: create, list, fetch, and delete HubSpot reports
- History: local audit log of all destructive operations run by the CLI
Output defaults to JSONL — a streaming, pipeable format where each line is a valid JSON object. Use --format json for a wrapped array with metadata, or --format table for a human-readable ASCII table.
Every write command supports a --dry-run flag that previews changes without applying them. Use it before running any mutation, especially against production accounts.
Authentication
The CLI supports two authentication modes:
- OAuth login: scoped to your HubSpot user-level permissions. Recommended for most agent workflows.
- Admin mode via service key: set a service key as
HUBSPOT_ACCESS_TOKEN. Required for schema operations, most delete operations, reliable pipeline stage, and owner metadata resolution, and certain association types. Use with caution — this token carries broader permissions and doesn't generate a per-user audit trail.
Access control for admins
Super admins can use App Governance (beta) to control which users can connect the Agent CLI to a HubSpot account via OAuth. This doesn't restrict who can download the binary, but it does gate account-level data access. Learn more about managing access to apps.
If your organization uses Claude Team or Enterprise, your admin will also need to allowlist api.hubapi.com in Claude's network egress settings before the CLI can install or run from a Cowork session. Setup steps are covered in the Agent CLI guide.
For the full command reference, authentication details, piping examples, and output format documentation, see the Agent CLI guide.
When is it happening?
The HubSpot Agent CLI is now in public beta. To give it a try open your favorite agentic coding tool like Claude or Codex and paste the following prompt:
Questions or comments? Join us in the developer forums.