hubspot-cli

Your AI Agent's Gateway to HubSpot CRM

The command-line interface designed for LLMs, automation pipelines, and developers who think in JSON.

---

Quick Start · For AI Agents · Examples · API Reference

The Problem

Traditional CLIs are built for humans. They output pretty tables, colorful text, and interactive prompts. That's great for manual use—but terrible for AI agents and automation.

When Claude, GPT, or your automation scripts interact with a CLI, they need:

• Predictable JSON output — not tables that break when columns change
• Machine-readable error codes — not "Something went wrong"
• Discoverable APIs — the ability to explore what's possible
• Consistent behavior — same input, same output, every time

hubspot-cli is built from the ground up for this world.

---

✨ Key Features

🤖 AI-Native Design { "success": true, "data": { ... }, "paging": { "next_cursor": "abc" } } Every command returns structured JSON. Errors include codes like RATE_LIMIT_EXCEEDED with actionable suggestions. No parsing HTML or guessing formats.	⚡ Blazing Fast Native Rust — 10ms startup, minimal memory Smart caching — metadata cached 1hr, objects 5min Rate limit aware — never hit HubSpot's limits Auto-retry — exponential backoff built-in
📦 Complete CRM Coverage Contacts, Companies, Deals, Tickets Products, Quotes, Line Items Custom Objects with schema discovery Associations & Pipelines Batch operations (up to 100 at once)	🔧 Production Ready Multi-account — named profiles for different portals Secure — tokens never logged, account-isolated cache Scriptable — consistent exit codes (0-10) Flexible output — JSON, pretty JSON, table, CSV

---

🚀 Quick Start

Install

# From crates.io
cargo install hubspot-cli

# Or download pre-built binary from GitHub Releases
# https://github.com/dipankar/hubspot-cli/releases

Configure

export HUBSPOT_ACCESS_TOKEN="pat-na1-xxxxxxxx"

Get your token: HubSpot Private Apps

Use

# Check authentication
hubspot auth status

# List contacts (returns JSON)
hubspot crm contacts list --limit 5

# Create a contact
hubspot crm contacts create --email "jane@acme.com" --firstname "Jane"

# Search deals over $50k
hubspot crm deals search --filter-groups '[{"filters":[{"propertyName":"amount","operator":"GTE","value":"50000"}]}]'

# Explore available properties
hubspot discover properties contacts

---

🤖 Designed for AI Agents

Structured Output — Always

Every command returns consistent JSON:

$ hubspot crm contacts get 12345

{
  "success": true,
  "data": {
    "id": "12345",
    "properties": {
      "email": "jane@example.com",
      "firstname": "Jane",
      "lastname": "Doe",
      "lifecyclestage": "customer"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-16T14:22:00Z"
  }
}

Errors That Help

When things go wrong, you get actionable information:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "category": "rate_limit",
    "suggestions": [
      "Wait 60 seconds before retrying",
      "Use batch operations to reduce API calls"
    ],
    "retry": {
      "retryable": true,
      "retry_after_seconds": 60
    }
  }
}

Self-Documenting API

Agents can discover capabilities at runtime:

# What CRM objects exist?
hubspot discover objects

# What properties can I use for contacts?
hubspot discover properties contacts

# What are the deal pipeline stages?
hubspot crm pipelines list deals

Exit Codes for Automation

Code	Meaning	Action
0	Success	Continue
3	Auth failed	Check token
5	Validation error	Fix input
6	Not found	Check ID
7	Rate limited	Wait & retry
8	Server error	Retry later

---

🐍 Integration Examples

Python Agent

import subprocess
import json

def hubspot(cmd: str) -> dict:
    """Execute hubspot-cli command and return parsed JSON."""
    result = subprocess.run(
        f"hubspot {cmd}",
        shell=True,
        capture_output=True,
        text=True
    )
    return json.loads(result.stdout)

# Discover available properties
props = hubspot("discover properties contacts")
print(f"Found {len(props['data'])} contact properties")

# List recent contacts
contacts = hubspot("crm contacts list --limit 10 -P email,firstname,lifecyclestage")
if contacts["success"]:
    for c in contacts["data"]:
        print(f"{c['properties']['email']} - {c['properties'].get('lifecyclestage', 'unknown')}")

# Create a contact
new_contact = hubspot('crm contacts create --email "lead@example.com" --firstname "New Lead"')
print(f"Created contact: {new_contact['data']['id']}")

Shell Script

#!/bin/bash
set -e

# Export contacts to CSV
hubspot crm contacts list --limit 1000 --output csv > contacts.csv

# Create contacts from JSON file
while IFS= read -r line; do
    email=$(echo "$line" | jq -r '.email')
    name=$(echo "$line" | jq -r '.name')
    hubspot crm contacts create --email "$email" --firstname "$name"
done < leads.json

# Check for rate limiting
result=$(hubspot discover rate-limits)
remaining=$(echo "$result" | jq '.data.daily_remaining')
echo "API calls remaining today: $remaining"

Claude/LLM Tool Definition

{
  "name": "hubspot_crm",
  "description": "Interact with HubSpot CRM via CLI",
  "parameters": {
    "command": {
      "type": "string",
      "description": "The hubspot-cli command to execute",
      "examples": [
        "crm contacts list --limit 10",
        "crm deals search --filter-groups '[{\"filters\":[{\"propertyName\":\"amount\",\"operator\":\"GTE\",\"value\":\"10000\"}]}]'",
        "discover properties contacts"
      ]
    }
  }
}

---

📖 Usage Examples

Contact Operations

# List with specific properties
hubspot crm contacts list --limit 100 -P email,firstname,company,lifecyclestage

# Get single contact
hubspot crm contacts get 12345 -P email,phone,company

# Create with all details
hubspot crm contacts create \
  --email "jane@acme.com" \
  --firstname "Jane" \
  --lastname "Doe" \
  --phone "+1-555-123-4567" \
  --company "Acme Inc"

# Update existing
hubspot crm contacts update 12345 --properties '{"lifecyclestage":"customer"}'

# Search by email domain
hubspot crm contacts search --query "email:*@acme.com"

# Batch create (up to 100)
hubspot crm contacts batch-create --inputs '[
  {"properties":{"email":"a@example.com","firstname":"Alice"}},
  {"properties":{"email":"b@example.com","firstname":"Bob"}}
]'

Deal Operations

# List deals in pipeline
hubspot crm deals list --limit 50 -P dealname,amount,dealstage

# Create deal
hubspot crm deals create \
  --dealname "Enterprise Contract" \
  --amount "150000" \
  --pipeline "default" \
  --stage "qualifiedtobuy"

# Search high-value deals
hubspot crm deals search --filter-groups '[{
  "filters": [
    {"propertyName": "amount", "operator": "GTE", "value": "100000"},
    {"propertyName": "dealstage", "operator": "NEQ", "value": "closedlost"}
  ]
}]'

Company & Ticket Operations

# Create company
hubspot crm companies create \
  --name "Acme Corporation" \
  --domain "acme.com" \
  --industry "Technology"

# Create support ticket
hubspot crm tickets create \
  --subject "Integration Issue" \
  --content "Customer reporting API timeout errors" \
  --priority "HIGH"

# List tickets by priority
hubspot crm tickets search --filter-groups '[{
  "filters": [{"propertyName": "hs_ticket_priority", "operator": "EQ", "value": "HIGH"}]
}]'

Discovery & Debugging

# List all CRM object types
hubspot discover objects

# Get contact properties (custom only)
hubspot discover properties contacts --custom-only

# Check rate limit status
hubspot discover rate-limits

# Preview command without executing
hubspot crm contacts create --email "test@test.com" --dry-run

---

⚙️ Configuration

Environment Variables

Variable	Description	Default
HUBSPOT_ACCESS_TOKEN	HubSpot private app token	required
HUBSPOT_PROFILE	Active profile name	default
HUBSPOT_OUTPUT_FORMAT	Output format (json, table, csv)	json
HUBSPOT_NO_CACHE	Disable caching	false

Config File

Location: ~/.config/hubspot-cli/config.toml

default_profile = "default"

[output]
format = "json"

[api]
base_url = "https://api.hubapi.com"
timeout_seconds = 30
max_retries = 3

[cache]
enabled = true
metadata_ttl_seconds = 3600   # Properties, schemas: 1 hour
objects_ttl_seconds = 300     # Contacts, deals: 5 minutes

[profiles.default]
access_token_env = "HUBSPOT_ACCESS_TOKEN"

[profiles.production]
access_token_env = "HUBSPOT_PROD_TOKEN"
portal_id = "123456"

[profiles.sandbox]
access_token_env = "HUBSPOT_SANDBOX_TOKEN"

Global Options

Option	Short	Description
--output	-o	Format: json, json-pretty, table, csv
--profile	-p	Use specific auth profile
--quiet	-q	Suppress non-essential output
--verbose	-v	Enable debug output
--no-cache		Bypass cache for this request
--dry-run		Preview without executing

---

Architecture

hubspot <domain> <object> <action> [options]
   │        │        │        │
   │        │        │        └── list, get, create, update, delete, search
   │        │        └── contacts, companies, deals, tickets, products, quotes...
   │        └── crm, auth, discover, config
   └── CLI binary

# Examples:
hubspot crm contacts list --limit 10
hubspot crm deals create --dealname "Big Deal" --amount 50000
hubspot discover properties contacts
hubspot auth status

---

Development

# Clone and build
git clone https://github.com/dipankar/hubspot-cli
cd hubspot-cli
cargo build --release

# Run tests (122 tests)
cargo test

# Format and lint
cargo fmt && cargo clippy

# Install locally
cargo install --path .

---

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for new functionality
4. Ensure cargo test and cargo clippy pass
5. Submit a Pull Request

---

License

MIT — see LICENSE for details.

---

Built for the AI-first era of software development.

GitHub · Crates.io · HubSpot API Docs