> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
---
id: cae9424f-2cff-4d2d-9342-d565d1424ba7
---
# Install and use the HubSpot Agent CLI (BETA)
> Learn how to install the HubSpot Agent CLI to allow AI agents to directly interact with CRM data in your account.
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:
```text wrap theme={null}
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](#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.
```shell wrap theme={null}
curl -fsSL https://api.hubapi.com/hub/cli/backend/hub-cli/latest/install.sh | sh
```
```shell wrap theme={null}
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:
```shell theme={null}
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:
```shell theme={null}
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](https://github.com/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](https://knowledge.hubspot.com/user-management/hubspot-user-permissions-guide#super-admin) 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](#control-access-with-app-governance-beta).
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.
### Standard mode via OAuth login
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:
```shell theme={null}
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:
```shell theme={null}
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](#admin-mode-via-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](#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](/apps/developer-platform/build-apps/authentication/account-service-keys) as an environment variable.
```shell theme={null}
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:
```shell theme={null}
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 `. To get more information about a given command, run `--help` at any level.
```shell theme={null}
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 ` | Fetch a single record by ID. |
| `objects search` | Filter records with search criteria. |
| `objects create` | Create one or many records. |
| `objects update ` | 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 ` | 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 ` | 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 ` | Update custom object schema metadata from JSON. Requires Admin mode via service key token and a `--dry-run` safety digest. |
| `schemas delete ` | 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 ` | Fetch one or more workflows by flow ID. |
| `workflows create` | Create a workflow from JSON. |
| `workflows update ` | Replace a workflow from JSON. Requires the `automation` scope and a `--dry-run` safety digest. |
| `workflows delete ` | Delete a workflow. Requires the `automation` scope and a `--dry-run` safety digest. |
| `views list` | List saved CRM index-page views for an object type. |
| `views get ` | Fetch a view's full definition, including columns, filters, and sort. |
| `views create ` | Create a saved CRM view with an ordered column list. |
| `views update ` | Add, remove, or reorder visible columns while preserving the rest of the view configuration. |
| `views replace-field ` | Replace a property in a view's columns and sort. Filters are left unchanged. |
| `views delete ` | Delete a saved view. Requires 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. Can include enriched transcript fields such as recording URL and AI summary. 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. |
| `reports create` | Create a saved report from a CRM SQL query. |
| `reports list` | List saved reports. |
| `reports get ` | Fetch a single saved report by ID. |
| `reports fetch-dataset ` | Re-execute a saved report and return its dataset. |
| `reports insights ` | Generate AI insights for a saved report. |
| `reports clone ` | Clone an existing report. |
| `reports favorite ` | Add a report to your favorites. |
| `reports unfavorite ` | Remove a report from your favorites. |
| `reports delete ` | Delete a saved report. Requires elevated privileges and a `--dry-run` safety digest. |
| `history` | View the local audit log for destructive operations. |
| `feedback ` | Send feedback about the Agent CLI to HubSpot. |
The currently supported top-level command groups are `objects`, `pipelines`, `properties`, `associations`, `owners`, `workflows`, `views`, `schemas`, `activities`, `reports`, `history`, and `feedback`. 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.
```shell theme={null}
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.
### 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:
```shell theme={null}
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:
```shell theme={null}
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:
```shell theme={null}
hubspot objects list --type contacts --properties email,firstname,lastname
```
### 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:
```shell theme={null}
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:
1. Search for a contact by their email, pipe the output to update the `tier` property of the matched contact to gold.
2. The corresponding output is first saved to a `plan.jsonl` file where the forthcoming results could first be reviewed.
3. 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.
```shell theme={null}
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
```
### 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`.
```shell theme={null}
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
```
#### Create contacts from a .jsonl file
The example below bulk-creates contacts from a `.jsonl` file:
```shell theme={null}
cat contacts.jsonl | hubspot objects create --type contacts
```
#### Bulk delete bounced contacts
The code block below retrieves all contacts who [bounced](https://knowledge.hubspot.com/marketing-email/what-is-the-difference-between-a-hard-bounce-and-a-soft-bounce) on a sent email and bulk-deletes them from your CRM:
```shell theme={null}
hubspot objects search --type contacts --filter "bounced=true" --format jsonl \
| jq -c '{id}' \
| hubspot objects delete --type contacts
```
### CRM saved views
Use `views` commands to inspect and manage saved CRM index-page views. Supported object type values include `contacts`, `companies`, `deals`, `tickets`, or a raw object type ID such as `0-1`.
List views for an object type:
```shell theme={null}
hubspot views list contacts --format table
```
Create a view with an ordered column list:
```shell theme={null}
hubspot views create contacts --name "VIP contacts" --columns email,firstname,lastname --sort email:asc
```
Preview column changes before writing them:
```shell theme={null}
hubspot views update contacts 12345 --add hs_lead_status --remove legacy_status --dry-run
```
Replace a property in the view's columns and sort:
```shell theme={null}
hubspot views replace-field contacts 12345 --from legacy_country --to country --dry-run
```
The `replace-field` command preserves the property's column position and sort when it can. Filters are left unchanged. If the original property is still used in a filter, the command returns a filter warning so you can review that filter separately.
Delete a saved view by running a dry run first, then re-running the command with the digest and confirmation value returned by the dry run:
```shell theme={null}
hubspot views delete contacts 12345 --dry-run
hubspot views delete contacts 12345 --digest blast-... --confirm "VIP contacts"
```
### Reports
Use `reports` commands to create reports from CRM SQL, retrieve saved report configuration, fetch report datasets, and manage report favorites.
Create a saved report from a CRM SQL query:
```shell theme={null}
hubspot reports create "SELECT dealstage, COUNT(*) FROM DEAL GROUP BY dealstage" \
--name "Deals by stage" \
--description "Count of deals grouped by stage" \
--chart-type HORIZONTAL_BAR \
--date-range THIS_MONTH \
--access-classification EVERYONE \
--permission-level VIEW
```
You can filter report data by owner or team:
```shell theme={null}
hubspot reports create "SELECT dealname, amount FROM DEAL WHERE amount > 10000" \
--name "High value deals" \
--filter-owners 12345 \
--filter-teams 67890
```
List and fetch saved reports:
```shell theme={null}
hubspot reports list --limit 25 --format table
hubspot reports get 12345 --format json
hubspot reports fetch-dataset 12345 --format json
```
Clone a report and manage favorites:
```shell theme={null}
hubspot reports clone 12345 --name "Copy of Deals by stage"
hubspot reports favorite 12345
hubspot reports unfavorite 12345
```
Generate AI insights for a saved report:
```shell theme={null}
hubspot reports insights 12345
```
Delete a saved report by running a dry run first, then re-running the command with the digest and report name returned by the dry run. This is expected to require the appropriate elevated privileges for destructive report operations.
```shell theme={null}
hubspot reports delete 12345 --dry-run
hubspot reports delete 12345 --digest blast-... --confirm "Deals by stage"
```
### Activity transcripts
Use `activities transcript get` to fetch the transcript for a call or meeting activity ID returned by `activities list`.
```shell theme={null}
hubspot activities transcript get 54321 --type CALL --format json
```
Transcript output can include enriched fields when that data is available: `recordingUrl`, `aiSummary`, `transcriptStatus`, `numUtterances`, and `transcriptionProvider`. To request only specific enriched fields, use `--fields`:
```shell theme={null}
hubspot activities transcript get 54321 --fields recordingUrl,aiSummary --format json
```
### 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. |
| `views list`, `views get`, `views create`, `views update`, `views replace-field` | Supported when OAuth can access and manage CRM views for the object type. Write commands support dry-run previews where available. | Use a service key if OAuth cannot access the view metadata or the operation requires account-level access. |
| `views delete` | Requires a safety digest and the permissions needed to delete the saved view. | Use a service key when the delete operation requires account-level 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. |
| `reports create`, `reports list`, `reports get`, `reports fetch-dataset`, `reports insights`, `reports clone`, `reports favorite`, `reports unfavorite` | Supported when OAuth has access to the reporting endpoints and the relevant account features. Report insights can depend on account feature availability. | Use a service key when the report endpoint requires account-level access or the workflow needs unattended account-level permissions. |
| `reports delete` | Requires the appropriate elevated privileges for destructive report operations and a safety digest. | Use a service key with the required report permissions. |
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.
## 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:
```shell theme={null}
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:
```text wrap theme={null}
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:
```shell theme={null}
export HUBSPOT_NO_AUTO_UPGRADE=1
```
To confirm which CLI version your scripts will use, run:
```shell theme={null}
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:
```shell theme={null}
rm -rf ~/.hubspot ~/.config/hubspot
```
```shell theme={null}
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.
1. In your Claude account, navigate to **Organization settings** > [**Capabilities**](https://claude.ai/admin-settings/capabilities).
2. Confirm **Code execution and file creation** is toggled on.
3. Under *Allow network egress*, select **Allow network egress to package managers and specific domains**.
4. 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](https://knowledge.hubspot.com/integrations/manage-access-to-ai-connectors).
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](#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.