hubspot-cli

A command-line interface for HubSpot CRM. Manage contacts, companies, deals, and more from your terminal.

Features

CRM Objects - Full CRUD operations for contacts, companies, deals, tickets, products, quotes, and line items
Engagements - Manage notes, calls, emails, meetings, and tasks
Marketing - Access forms, campaigns, and marketing emails
CMS - Manage files, pages, blogs, and HubDB tables
Automation - List and manage workflows, enroll objects
GraphQL - Execute queries and explore the schema
Multiple output formats - Table (default), JSON, or plain text

Installation

macOS

Homebrew (recommended)

brew install open-cli-collective/tap/hspt

Windows

Chocolatey

choco install hspt

Winget

winget install OpenCLICollective.hspt

Linux

Binary download

Download .deb, .rpm, or .tar.gz from the Releases page.

From Source

go install github.com/open-cli-collective/hubspot-cli/cmd/hspt@latest

Setup

1. Create a HubSpot Private App

Go to your HubSpot account Settings > Integrations > Private Apps
Click Create a private app
Name it (e.g., "CLI Access")
Under Scopes, select the permissions you need:
- CRM: crm.objects.contacts.read, crm.objects.contacts.write, etc.
- Marketing: forms, content
- Automation: automation
Click Create app
Copy the access token shown

2. Configure hspt

Run the init command:

hspt init

You'll be prompted to enter your access token. Alternatively, set it via environment variable:

export HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxx

3. Verify Setup

hspt config test

Commands

Configuration

# Guided setup
hspt init

# Check configuration status
hspt config show

# Set access token
hspt config set --token pat-na1-xxxxx

# Test API connectivity
hspt config test

# Clear stored configuration
hspt config clear

# Show version
hspt --version

CRM Objects

All CRM object commands follow the same pattern with list, get, create, update, delete, and search subcommands.

Command	Description
`contacts`	Manage CRM contacts
`companies`	Manage CRM companies
`deals`	Manage CRM deals
`tickets`	Manage support tickets
`owners`	View CRM owners (users)
`products`	Manage products
`line-items`	Manage line items
`quotes`	Manage quotes

Examples:

# List contacts
hspt contacts list --limit 20

# Search contacts by email
hspt contacts search --email john@example.com

# Get a specific contact
hspt contacts get 12345

# Create a contact
hspt contacts create --email jane@example.com --firstname Jane --lastname Doe

# Update a contact
hspt contacts update 12345 --phone "+1-555-0100"

# Delete a contact (requires --force)
hspt contacts delete 12345 --force

# Output as JSON
hspt contacts list -o json

# List deals with custom properties
hspt deals list --properties dealname,amount,closedate

# Search deals by stage
hspt deals search --stage closedwon --limit 50

# Create a deal
hspt deals create --name "Enterprise Deal" --amount 50000 --stage qualifiedtobuy

Engagements

Command	Description
`notes`	Manage notes attached to records
`calls`	Manage call records
`emails`	Manage email activities
`meetings`	Manage meeting records
`tasks`	Manage tasks

Examples:

# List recent notes
hspt notes list --limit 10

# Create a task
hspt tasks create --subject "Follow up" --body "Call about renewal" --priority HIGH

# Log a call
hspt calls create --body "Discussed pricing" --direction OUTBOUND --duration 300

Associations

# List companies associated with a contact
hspt associations list --from-type contacts --from-id 123 --to-type companies

# Create an association
hspt associations create --from-type contacts --from-id 123 --to-type companies --to-id 456

# Delete an association (requires --force)
hspt associations delete --from-type contacts --from-id 123 --to-type companies --to-id 456 --force

Properties

# List properties for contacts
hspt properties list --object-type contacts

# Get property details
hspt properties get --object-type contacts --name email

# Create a custom property
hspt properties create --object-type contacts --name custom_field --label "Custom Field" --type string --field-type text

# Delete a property (requires --force)
hspt properties delete --object-type contacts --name custom_field --force

Pipelines

# List deal pipelines
hspt pipelines list --object-type deals

# Get pipeline details
hspt pipelines get --object-type deals --id default

# List pipeline stages
hspt pipelines stages --object-type deals --id default

Custom Object Schemas

Requires Operations Hub Professional or Enterprise.

# List custom object schemas
hspt schemas list

# Get schema details
hspt schemas get p_my_custom_object

# Create schema from JSON file
hspt schemas create --file schema.json

# Delete schema (requires --force)
hspt schemas delete p_my_custom_object --force

Marketing

Command	Description
`forms`	View forms and submissions
`campaigns`	View marketing campaigns
`marketing-emails`	Manage marketing emails

Examples:

# List forms
hspt forms list

# Get form submissions
hspt forms submissions 

# List campaigns
hspt campaigns list

# List marketing emails
hspt marketing-emails list

CMS

Command	Description
`files`	Manage files in File Manager
`domains`	View domains
`pages`	Manage site and landing pages
`blogs`	Manage blog posts, authors, and tags
`hubdb`	Manage HubDB tables and rows

Examples:

# List files
hspt files list

# List folders
hspt files folders

# List site pages
hspt pages list --type site

# List landing pages
hspt pages list --type landing

HubDB:

# List HubDB tables
hspt hubdb tables list

# Get table details
hspt hubdb tables get my_table

# List rows in a table
hspt hubdb rows list my_table

# Create a row
hspt hubdb rows create my_table --file row.json

# Publish table changes
hspt hubdb tables publish my_table

Conversations

# List inboxes
hspt conversations inboxes list

# List threads
hspt conversations threads list

# Get thread details
hspt conversations threads get 

# List messages in a thread
hspt conversations messages list 

# Send a message
hspt conversations messages send  --text "Hello!" --channel-id

Workflows

# List workflows
hspt workflows list

# Get workflow details
hspt workflows get 

# Create workflow from JSON
hspt workflows create --file workflow.json

# Update workflow
hspt workflows update  --file workflow.json

# Delete workflow (requires --force)
hspt workflows delete  --force

# Enroll an object in a workflow
hspt workflows enroll  --object-id 

# List workflow enrollments
hspt workflows enrollments

GraphQL

Execute queries against HubSpot's unified GraphQL API.

# Execute query from file
hspt graphql query --file query.graphql

# Execute inline query
hspt graphql query --query '{ CRM { contact_collection(limit: 10) { items { email } } } }'

# Query with associations
hspt graphql query --query '{
  CRM {
    contact_collection(limit: 5) {
      items {
        firstname
        email
        associations {
          company_collection { items { name } }
        }
      }
    }
  }
}'

Schema exploration:

# List available types
hspt graphql explore

# Show fields of a type
hspt graphql explore --type CRM

# Show field details
hspt graphql explore --type CRM --field contact_collection

Global Flags

All commands support these flags:

Flag	Description
`-o, --output`	Output format: `table` (default), `json`, `plain`
`--no-color`	Disable colored output
`-v, --verbose`	Enable verbose output

Examples:

# JSON output for scripting
hspt contacts list -o json

# Plain output for simple lists
hspt contacts list -o plain

# Disable colors (useful in CI)
hspt contacts list --no-color

Common Patterns

Pagination

Most list commands support pagination:

# Limit results
hspt contacts list --limit 50

# Get next page
hspt contacts list --after

The cursor for the next page is shown in the output when more results are available.

Custom Properties

Specify which properties to return:

hspt contacts list --properties email,firstname,lastname,company

Set custom properties when creating or updating:

hspt contacts create --email test@example.com --prop custom_field=value --prop another_field=123

Destructive Operations

Delete commands require --force to confirm:

# Shows warning without executing
hspt contacts delete 12345

# Actually deletes
hspt contacts delete 12345 --force

Shell Completion

hspt supports tab completion for bash, zsh, fish, and PowerShell.

Bash

# Load in current session
source &lt;(hspt completion bash)

# Install permanently (Linux)
hspt completion bash | sudo tee /etc/bash_completion.d/hspt &gt; /dev/null

# Install permanently (macOS with Homebrew)
hspt completion bash &gt; $(brew --prefix)/etc/bash_completion.d/hspt

Zsh

# Load in current session
source &lt;(hspt completion zsh)

# Install permanently
mkdir -p ~/.zsh/completions
hspt completion zsh &gt; ~/.zsh/completions/_hspt

# Add to ~/.zshrc if not already present:
# fpath=(~/.zsh/completions $fpath)
# autoload -Uz compinit &amp;&amp; compinit

Fish

# Load in current session
hspt completion fish | source

# Install permanently
hspt completion fish &gt; ~/.config/fish/completions/hspt.fish

PowerShell

# Load in current session
hspt completion powershell | Out-String | Invoke-Expression

# Install permanently (add to $PROFILE)
hspt completion powershell &gt;&gt; $PROFILE

Configuration

Configuration is stored in ~/.config/hubspot-cli/config.json:

{
  "access_token": "pat-na1-xxxxx"
}

Environment Variables

Variable	Description
`HUBSPOT_ACCESS_TOKEN`	HubSpot private app access token

Environment variables take precedence over the config file.

Troubleshooting

"401 Unauthorized" or "Invalid token"

Your access token is invalid or expired:

hspt config clear
hspt init

"403 Forbidden" or "Missing scopes"

Your private app doesn't have the required scopes for this operation. Edit your private app in HubSpot Settings to add the needed scopes.

Test Connection

Verify your configuration:

hspt config test

Verbose Mode

For debugging, use verbose mode:

hspt --verbose contacts list

License

MIT License - see LICENSE for details.

HubSpot CLI Open CLI Collective

README

hubspot-cli

Features

Installation

macOS

Windows

Linux

From Source

Setup

1. Create a HubSpot Private App

2. Configure hspt

3. Verify Setup

Commands

Configuration

CRM Objects

Engagements

Associations

Properties

Pipelines

Custom Object Schemas

Marketing

CMS

Conversations

Workflows

GraphQL

Global Flags

Common Patterns

Pagination

Custom Properties

Destructive Operations

Shell Completion

Bash

Zsh

Fish

PowerShell

Configuration

Environment Variables

Troubleshooting

"401 Unauthorized" or "Invalid token"

"403 Forbidden" or "Missing scopes"

Test Connection

Verbose Mode

License