Install and use the HubSpot Agent CLI (BETA)

This functionality is currently in beta. By participating in this beta, you agree to HubSpot’s Developer Terms and Developer Beta Terms. Note that the functionality is still under active development: commands, flags, and behavior may change without notice.Write operations (create, update, and delete) can modify or permanently delete live data in your account. If you run the CLI against a production account, you accept the risk of unintended changes, including data loss. It’s strongly recommended that you use the --dry-run flag before applying mutations and test in a sandbox account whenever possible.

The HubSpot Agent CLI is a command-line tool designed primarily for AI agents, such as Claude Code, Claude Cowork, and OpenAI Codex. Agents can install and use the CLI to work directly with your HubSpot CRM data and operate on your behalf. You can also run the Agent CLI yourself on your local computer to test it out and leverage the functionality for custom scripting.

Installation

Install via an AI agent

If you’re setting up the Agent CLI for use with an AI agent, such as Claude Code, Claude Cowork, or Codex, the agent should be able to discover the CLI capabilities on its own using the --help flag. Relevant information will be provided to the agent down through the command tree, and your agent can then read output shapes and compose the corresponding pipelines for each command. The prompt below provides a starting point you can use with your AI agent:

Install the HubSpot Agent CLI in this agent workspace. If this workspace uses a POSIX shell (macOS, Linux, WSL, or Bash), run `curl -fsSL https://api.hubapi.com/hub/cli/backend/hub-cli/latest/install.sh | sh`. If it uses Windows PowerShell, run `irm https://api.hubapi.com/hub/cli/backend/hub-cli/latest/install.ps1 | iex`. Then authenticate with `hubspot auth login`, install HubSpot Agent CLI Skills with `npx skills add hubspot/agent-cli-skills`, and use `hubspot --help` to explore what's available.

If you’re using Claude Cowork in a Team or Enterprise account, your organization’s admin may need to allowlist api.hubapi.com before the CLI can install or run. Check out the Using the CLI with Claude Cowork section below for setup instructions.

Install the Agent CLI manually

The Agent CLI is packaged as a single binary with no runtime dependencies, and is supported for macOS, Linux, and Windows.

macOS/Linux
Windows PowerShell

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

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

The installer adds the CLI to your PATH. After installation, open a new terminal window or tab so the PATH change takes effect. You can verify that the installation was successful by running the command below:

hubspot --version

Add HubSpot Agent CLI Skills

If you installed the Agent CLI manually for use in an AI-agent workspace, install HubSpot Agent CLI Skills in that same workspace using the command below:

npx skills add hubspot/agent-cli-skills

After installation, ask your agent to use HubSpot Agent CLI Skills when planning HubSpot CRM tasks. The skills include guidance for bulk operations, CRM lookup, data quality, workflow automation, and other common tasks. Use the public GitHub repository hubspot/agent-cli-skills to inspect the skills that will be installed and available to your agent. Then use npx skills update to keep your skills library up to date in the installed agent workspace.

Authenticate with your HubSpot account

During beta testing, it’s recommended that admins also participate in App Governance (Beta). App Governance gives Super Admins control over who can connect the Agent CLI through hubspot auth login. Users without install access can request approval before connecting. Learn more about controlling access with App Governance.

Once installed, you can authenticate the CLI with your HubSpot account. Most users should use OAuth login, while service key tokens are available for admin, schema, destructive, or automation workflows that need account-level API access. If you plan on using the Agent CLI based on the scopes your HubSpot user has access to, such as reading owned records, running searches, or creating and updating records for standard and custom CRM objects, authenticate via OAuth login by running the command below:

hubspot auth login

This will open a browser window for you to authorize the CLI with your HubSpot account. The resulting token is scoped to your user-level permissions, which mirrors the same access you have when accessing your account through the HubSpot UI. The token will be refreshed automatically. If you ever need to clear cached credentials, run the following command:

hubspot auth logout

Current OAuth limitations: during the beta, some account-level metadata, schema, relationship, activity, and destructive operations are not supported with OAuth login alone and require a service key token. Some destructive commands also require a local --dry-run safety digest before they execute. These operations are detailed in the Auth-sensitive commands section below.

Admin mode via service key token

To perform account-level operations and bypass OAuth for API requests, you can set up a service key as an environment variable.

export HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

You can also add the service key in a .env file at ~/.hubspot/.env or ~/.config/hubspot/.env. When HUBSPOT_ACCESS_TOKEN is set, the Agent CLI uses it for HubSpot API requests before checking cached OAuth credentials. To return to OAuth mode in the same shell, run unset HUBSPOT_ACCESS_TOKEN. Once set up, the Agent CLI can perform operations that user-level OAuth tokens may not be able to perform, such as writing schema metadata, deleting records, reading and writing custom object schemas, and calling account-level relationship or activity endpoints. The exact commands available depend on the scopes and permissions granted to the service key.

Please note: use admin mode with caution. The token has broader permissions and will not include a per-user audit trail.

Check your session status

You can verify the authenticated user, token type, and authenticated HubSpot account ID by running the following command:

hubspot whoami

With OAuth login, whoami shows the authenticated user, account ID, and granted scopes. With HUBSPOT_ACCESS_TOKEN, it validates the token and shows the account ID, but user and OAuth scope details are not available.

Run commands

After you authenticate, the Agent CLI can run commands to perform actions in your account.

Command structure

Commands follow the pattern of hubspot <noun> <verb>. To get more information about a given command, run --help at any level.

hubspot --help                    # list all nouns
hubspot objects --help            # list verbs for objects
hubspot objects list --help       # flags, examples, and output shape

Core commands

The current data and automation commands are detailed in the table below:

Command	Description
`objects types`	List available CRM object types for the account.
`objects list`	List CRM records (contacts, companies, deals, tickets, custom objects).
`objects get <id>`	Fetch a single record by ID.
`objects search`	Filter records with search criteria.
`objects create`	Create one or many records.
`objects update <id>`	Update one or many records.
`objects merge`	Merge two records. The secondary record is folded into the primary record and deleted.
`objects upsert`	Create or update records by a unique property value.
`objects delete <id>`	Delete one or many records. May require Admin mode via service key token and a `--dry-run` safety digest.
`pipelines list`	List pipelines for an object type.
`pipelines get`	Fetch a single pipeline by ID.
`pipelines create`	Create a pipeline from JSON.
`pipelines update`	Update a pipeline’s label.
`pipelines delete`	Delete a pipeline. Requires a `--dry-run` safety digest and may require Admin mode via service key token.
`pipelines stages`	List stages in a pipeline.
`pipelines stages-get`	Fetch a single pipeline stage.
`pipelines stages-create`	Create a pipeline stage from JSON.
`pipelines stages-update`	Update a pipeline stage’s label.
`pipelines stages-delete`	Delete a pipeline stage. Requires a `--dry-run` safety digest and may require Admin mode via service key token.
`properties list`	List properties for an object type.
`properties get`	Fetch a single property by name.
`properties create`	Create a custom property. Requires property or schema write access for the object type.
`properties update`	Update a property’s label or group. Requires property or schema write access for the object type.
`properties delete`	Archive a property. Requires a `--dry-run` safety digest and may require Admin mode via service key token.
`properties batch-read`	Batch read properties by name.
`properties batch-create`	Batch create properties from JSONL. Requires property or schema write access for the object type.
`properties batch-archive`	Batch archive properties by name. Requires a `--dry-run` safety digest and may require Admin mode via service key token.
`associations list`	List associations between records.
`associations create`	Create associations between records. Requires association write access to the participating object types.
`associations delete`	Remove all associations between two records. Requires association write access to the participating object types.
`associations batch-read`	Batch read associations from piped record IDs.
`associations batch-delete`	Batch remove all associations from JSONL. Requires a `--dry-run` safety digest and may require Admin mode via service key token.
`associations batch-delete-labels`	Batch remove specific labeled associations from JSONL. Requires a `--dry-run` safety digest and may require Admin mode via service key token.
`associations labels-list`	List association label types between two object types.
`associations labels-create`	Create a custom association label type. May require Admin mode via service key token.
`associations labels-update`	Update a custom association label’s name. May require Admin mode via service key token.
`associations labels-delete`	Delete a custom association label type. Requires a `--dry-run` safety digest and may require Admin mode via service key token.
`associations limits-list`	List association limit configurations.
`associations limits-get`	Get association limits between two object types.
`associations limits-create`	Batch create association limits from JSONL. May require Admin mode via service key token.
`associations limits-update`	Batch update association limits from JSONL. May require Admin mode via service key token.
`associations limits-delete`	Batch delete association limits from JSONL. Requires a `--dry-run` safety digest and may require Admin mode via service key token.
`owners list`	List HubSpot users. Requires owner read access.
`schemas list`	List custom object schemas. Requires Admin mode via service key token.
`schemas get <objectType>`	Fetch a single custom object schema. Requires Admin mode via service key token.
`schemas create`	Create a custom object schema from JSON. Requires Admin mode via service key token.
`schemas update <objectType>`	Update custom object schema metadata from JSON. Requires Admin mode via service key token and a `--dry-run` safety digest.
`schemas delete <objectType>`	Delete a custom object schema and its records. Requires Admin mode via service key token and a `--dry-run` safety digest.
`workflows list`	List workflows.
`workflows get <flowId>`	Fetch one or more workflows by flow ID.
`workflows create`	Create a workflow from JSON.
`workflows update <flowId>`	Replace a workflow from JSON. Requires the `automation` scope and a `--dry-run` safety digest.
`workflows delete <flowId>`	Delete a workflow. Requires the `automation` scope and a `--dry-run` safety digest.
`activities list`	List activity history for a CRM record.
`activities transcript get`	Fetch the transcript for a call or meeting activity. May require Admin mode via service key token.
`activities transcript delete`	Delete the transcript for a call or meeting activity. Requires a `--dry-run` safety digest and may require Admin mode via service key token.
`activities emails threads get`	Fetch all messages in the thread for an email engagement. May require Admin mode via service key token.
`activities calls dispositions list`	List available call disposition labels for the account.
`history`	View the local audit log for destructive operations.

The currently supported top-level command groups are objects, pipelines, properties, associations, owners, workflows, schemas, activities, and history. The auth, whoami, upgrade, and help commands are covered in the relevant sections of this guide.

Object types

Use objects types to list the CRM object types available in the connected account, including custom objects and newer standard CRM object types.

hubspot objects types

For commands that accept --type, use the name value returned by objects types. Custom objects discovered this way work through the same object and property commands as other CRM object types, subject to the auth-sensitive operations listed below.

Auth-sensitive commands

Most read and non-destructive write commands can run with either OAuth login or HUBSPOT_ACCESS_TOKEN, as long as the token has the required scopes. Some commands are auth-sensitive because they call account-level endpoints, require service key permissions, or need a local --dry-run safety digest before the CLI can execute the operation. Use the table below to choose an auth mode for common command groups:

Command group	OAuth login support	When to use `HUBSPOT_ACCESS_TOKEN`
`objects list`, `objects get`, `objects search`	Supported with object read scopes.	Use a service key when reading object types or custom object metadata that OAuth cannot access.
`objects create`, `objects update`, `objects merge`, `objects upsert`	Supported with object write scopes for normal writes. Large bulk updates, merges, or upserts may require a safety digest.	Use a service key when the API requires account-level access or when automation needs account-level permissions.
`objects delete`	May be blocked by account-level endpoint permissions. Bulk or GDPR deletes require a safety digest.	Use a service key with object write/delete permission for delete operations.
`pipelines list`, `pipelines get`, `pipelines stages`, `pipelines stages-get`	Supported with pipeline and object read access.	Use a service key if a pipeline metadata endpoint returns an account-level auth error.
`pipelines create`, `pipelines update`, `pipelines stages-create`, `pipelines stages-update`	Supported with pipeline write access.	Use a service key if OAuth cannot write pipeline metadata.
`pipelines delete`, `pipelines stages-delete`	Requires a safety digest and may require account-level access.	Use a service key for destructive pipeline operations.
`properties list`, `properties get`, `properties batch-read`	Supported with property or schema read access.	Use a service key if OAuth cannot read property metadata for the object type.
`properties create`, `properties update`, `properties batch-create`	Supported when OAuth has the required property or schema write scopes.	Use a service key for account-level schema or property administration.
`properties delete`, `properties batch-archive`	Requires a safety digest and may require account-level access.	Use a service key for destructive property operations.
`associations list`, `associations batch-read`	Supported with object and association read access.	Use a service key if label or association metadata endpoints return account-level auth errors.
`associations create`, `associations delete`, `associations labels-create`, `associations labels-update`, `associations limits-create`, `associations limits-update`	Supported when OAuth has the required object and association permissions; some label or limit endpoints may require account-level access.	Use a service key for account-level association definition or limit changes.
`associations batch-delete`, `associations batch-delete-labels`, `associations labels-delete`, `associations limits-delete`	Requires a safety digest and may require account-level access.	Use a service key for destructive association metadata or bulk association removal.
`owners list`	Supported with owner read access.	Use a service key if OAuth cannot access owner metadata.
`schemas list`, `schemas get`, `schemas create`	Requires account-level custom schema access.	Use a service key with custom schema read or write scopes.
`schemas update`, `schemas delete`	Requires account-level custom schema access and a safety digest.	Use a service key with custom schema write scopes.
`workflows list`, `workflows get`, `workflows create`	Supported with the `automation` scope.	Use a service key for account-level workflow automation tasks or unattended automation.
`workflows update`, `workflows delete`	Requires the `automation` scope and a safety digest.	Use a service key when the workflow operation needs account-level automation access.
`activities list`	Supported when OAuth can read the base record and associated activity object types.	Use a service key if activity object reads are blocked by scopes or account-level permissions.
`activities transcript get`, `activities transcript delete`, `activities emails threads get`, `activities calls dispositions list`	Some activity media and thread endpoints may require account-level access. Transcript delete requires a safety digest.	Use a service key with the relevant calling transcript, email, or activity scopes.

If a command fails with a missing-scope error, the auth mode is usually supported but the token needs additional scopes. With OAuth login, run hubspot auth login --force and approve the requested scopes. With HUBSPOT_ACCESS_TOKEN, update the service key scopes, export the updated token, and retry. If a command fails with an account-level endpoint error, such as User level OAuth token is not allowed for this endpoint, set HUBSPOT_ACCESS_TOKEN to a service key token with the required permissions. Some destructive commands require a local safety digest from a --dry-run before they execute. If you are using HUBSPOT_ACCESS_TOKEN and a safety digest command asks you to run hubspot auth login, sign in once with OAuth, keep HUBSPOT_ACCESS_TOKEN set, and retry the dry-run and apply flow.

Output formats

The CLI defaults to JSONL, which is a UTF-8 encoded text format where each line is a valid independent JSON object, separated by newline characters (\n). Though JSONL is the format that AI agents work best with, you can also use the --format flag to format the output of a command in standard JSON with metadata or a human-readable ASCII table:

hubspot objects list --type contacts --format jsonl   # default — streaming, pipeable
hubspot objects list --type contacts --format json    # wrapped JSON array with metadata
hubspot objects list --type contacts --format table   # human-readable ASCII table

Filter and search

Use the objects search command in tandem with the --filter flag to search your account for records that meet the criteria you specify. The code block below provides examples of how to filter by email address or filter by multiple properties:

hubspot objects search --type contacts --filter "email=jane@example.com"
hubspot objects search --type deals --filter "amount>10000 AND dealstage=closedwon"

Properties

By default, object read commands return the raw API response, including the properties object. You can request specific properties by including the --properties flag. This will flatten the requested properties so each property appears as a top-level field, prefixed with prop_. For example, the following command would retrieve contacts and only list their email address, first name, and last name:

hubspot objects list --type contacts --properties email,firstname,lastname

Piping and bulk operations

One of the main strengths of the Agent CLI is the ability to compose commands through standard Unix pipes. Mutation commands (create, update, and delete) accept JSONL on stdin, so omit any positional arguments and pipe in one record per line. Check out the examples in the sections below.

Find contacts by email address and update a property

The example below retrieves all contacts with an email containing .edu and updates their segment property to be academic.

hubspot objects list --type contacts --properties email --format jsonl \
  | jq -c 'select((.prop_email // "") | test("@.*\\.edu$")) | {id}' \
  | hubspot objects update --type contacts --property segment=academic

Bulk delete bounced contacts

The code block below retrieves all contacts who bounced on a sent email and bulk-deletes them from your CRM:

hubspot objects search --type contacts --filter "bounced=true" --format jsonl \
  | jq -c '{id}' \
  | hubspot objects delete --type contacts

Create contacts from a .jsonl file

The example below bulk-creates contacts from a .jsonl file:

cat contacts.jsonl | hubspot objects create --type contacts

Using the dry run flag

Every write command supports the --dry-run flag, which will display a preview of what will happen without making any changes. For example, the code block below demonstrates a dry run of updating a specific contact to change its lifecycle stage to customer:

hubspot objects update --type contacts 12345 --property lifecyclestage=customer --dry-run

The output of a command run with the --dry-run flag is shape-compatible with the input to subsequent commands, so you can review a plan then execute it. The example below highlights chained commands with the --dry-run flag:

Search for a contact by their email, pipe the output to update the tier property of the matched contact to gold.
The corresponding output is first saved to a plan.jsonl file where the forthcoming results could first be reviewed.
Once reviewed, the plan.jsonl file could then be piped directly into the objects update command without the --dry-run flag to actually make the change.

hubspot objects search --type contacts --filter "email~example.com" --format jsonl \
  | hubspot objects update --type contacts --property tier=gold --dry-run > plan.jsonl

cat plan.jsonl | hubspot objects update --type contacts

Keep the CLI up to date

Choose an option below based on whether you installed the CLI manually on your computer or the CLI is installed in an agent workspace:

Installed on your computer

To download and install the latest Agent CLI binary, run:

hubspot upgrade

If you also installed HubSpot Agent CLI Skills in this workspace, run npx skills update to keep your skills library up to date.

Installed in an agent workspace

Provide the prompt below to your AI agent to initiate the update process:

Use the command `hubspot upgrade` in the workspace you previously installed the HubSpot Agent CLI to get the latest version. Then use `npx skills update` in the same workspace to check for new or updated HubSpot Agent CLI Skills. Confirm when both commands have completed successfully or if there were any errors and the appropriate resolution steps.

Disable automatic upgrades

Technical users who rely on generated scripts can disable automatic upgrade checks to keep CLI behavior consistent and reduce the risk that future breaking changes are installed automatically before those scripts are reviewed. To disable automatic upgrade checks for normal commands, set:

export HUBSPOT_NO_AUTO_UPGRADE=1

To confirm which CLI version your scripts will use, run:

hubspot --version

This setting applies to automatic upgrade checks for normal commands. You can still install an update explicitly with hubspot upgrade.

Uninstall the Agent CLI

To manually uninstall the Agent CLI, run the command for your operating system to remove the binary and local configuration:

macOS/Linux
Windows PowerShell

rm -rf ~/.hubspot ~/.config/hubspot

Remove-Item -Recurse -Force "$HOME\.hubspot", "$env:APPDATA\hubspot" -ErrorAction SilentlyContinue

Then, remove the PATH entry that was added as part of the initial installation (e.g., from ~/.zshrc, ~/.bashrc, ~/.config/fish/config.fish, or your Windows user PATH).

Using the CLI with Claude Cowork

The CLI communicates with HubSpot via api.hubapi.com. In Claude Team and Enterprise accounts, outbound network access is restricted by default, which will cause install and upgrade commands to fail with a network error. This only affects organizations where an admin has not yet configured network egress permissions. If the CLI fails to install or run inside a Cowork session, have your Claude organization admin complete the steps below. Note that your admin will need a Team/Enterprise Owner or Primary Owner role in Claude.

In your Claude account, navigate to Organization settings > Capabilities.
Confirm Code execution and file creation is toggled on.
Under Allow network egress, select Allow network egress to package managers and specific domains.
Add api.hubapi.com to the allowed domains list and save.

Once saved, users in the organization can install and run the CLI from Cowork without additional configuration.

Control access with App Governance (Beta)

Most users should authenticate the Agent CLI with hubspot auth login. This starts the OAuth app install flow for HubSpot Agent CLI. Super Admins can use App Governance (Beta) to control who can connect the Agent CLI to a HubSpot account. This does not control whether someone can download the local hubspot binary, but it does control whether the CLI can be authorized to access account data. To manage access, go to Settings > Integrations > Connected Apps > Approved apps, then find HubSpot Agent CLI. From there, Super Admins can approve the connector, choose who can install it, and configure optional data permissions. Learn more about managing access to apps. If a user does not have install access, a request screen will appear after they execute the hubspot auth login command. The user can request approval from an account admin, optionally select approvers, add a due date, and include a message. After they’re approved, they can continue connecting the Agent CLI. For admin or automation workflows that use a service key token, see Admin mode via service key token. Service key token access is separate from the user-level OAuth install flow and should be limited to trusted admin-controlled environments. App Governance controls access to the OAuth connector, but does not remove current service key requirements for Admin mode operations.

​Installation

​Install via an AI agent

​Install the Agent CLI manually

​Add HubSpot Agent CLI Skills

​Authenticate with your HubSpot account

​Standard mode via OAuth login

​Admin mode via service key token

​Check your session status

​Run commands

​Command structure

​Core commands

​Object types

​Auth-sensitive commands

​Output formats

​Filter and search

​Properties

​Piping and bulk operations

​Find contacts by email address and update a property

​Bulk delete bounced contacts

​Create contacts from a .jsonl file

​Using the dry run flag

​Keep the CLI up to date

​Installed on your computer

​Installed in an agent workspace

​Disable automatic upgrades

​Uninstall the Agent CLI

​Using the CLI with Claude Cowork

​Control access with App Governance (Beta)

Installation

Install via an AI agent

Install the Agent CLI manually

Add HubSpot Agent CLI Skills

Authenticate with your HubSpot account

Standard mode via OAuth login

Admin mode via service key token

Check your session status

Run commands

Command structure

Core commands

Object types

Auth-sensitive commands

Output formats

Filter and search

Properties

Piping and bulk operations

Find contacts by email address and update a property

Bulk delete bounced contacts

Create contacts from a .jsonl file

Using the dry run flag

Keep the CLI up to date

Installed on your computer

Installed in an agent workspace

Disable automatic upgrades

Uninstall the Agent CLI

Using the CLI with Claude Cowork

Control access with App Governance (Beta)