Content
<div align="center">
# 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.*
[](https://www.npmjs.com/package/hubspot-cli)
[](https://crates.io/crates/hubspot-cli)
[](https://crates.io/crates/hubspot-cli)
[](https://github.com/dipankar/hubspot-cli/actions)
[](LICENSE)
---
**[Quick Start](#-quick-start)** · **[For AI Agents](#-designed-for-ai-agents)** · **[Examples](#-usage-examples)** · **[API Reference](#architecture)**
</div>
## 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
<table>
<tr>
<td width="50%">
### 🤖 AI-Native Design
```json
{
"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.
</td>
<td width="50%">
### ⚡ 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
</td>
</tr>
<tr>
<td width="50%">
### 📦 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)
</td>
<td width="50%">
### 🔧 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
- **Claude-native** — `skill-install` ships Claude Code skills, `mcp serve` exposes every command over MCP
</td>
</tr>
</table>
---
## 🚀 Quick Start
### Install
```bash
# From npm (recommended — no Rust toolchain needed)
npm install -g hubspot-cli
# Or run directly with npx
npx hubspot-cli crm contacts list
# From crates.io
cargo install hubspot-cli
# Or download pre-built binary from GitHub Releases
# https://github.com/dipankar/hubspot-cli/releases
```
### Configure
```bash
export HUBSPOT_ACCESS_TOKEN="pat-na1-xxxxxxxx"
```
Get your token: [HubSpot Private Apps](https://app.hubspot.com/private-apps/)
### Use
```bash
# 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:
```bash
$ hubspot crm contacts get 12345
```
```json
{
"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:
```json
{
"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:
```bash
# 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 |
---
## 🧠 Claude-Native: Skills + MCP
`hubspot-cli` ships with two first-class Claude integrations. Pick whichever matches how you work — or use both.
### Claude Code Skills
One command installs eight curated **Claude Code skills**, one per CRM object. Claude auto-discovers them and loads only the relevant skill when the user mentions contacts, deals, tickets, and so on.
```bash
# Install to ~/.claude/skills (default)
hubspot skill-install
# Or install into the current project (./.claude/skills), versioned with git
hubspot skill-install --project
# Preview without writing
hubspot skill-install --dry-run
# Only install a subset
hubspot skill-install --only contacts,deals
```
After installing, open Claude Code in any project and ask:
> "Find the five most recent HubSpot contacts in lifecycle stage customer."
Claude loads `hubspot-contacts`, runs the right `hubspot crm contacts search …` invocation, and parses the JSON envelope. Full details: [documentation/docs/llm-integration/skills.md](documentation/docs/llm-integration/skills.md).
### Model Context Protocol (MCP) Server
`hubspot mcp serve` runs a JSON-RPC 2.0 MCP server on stdio that exposes every CRM operation — contacts, companies, deals, tickets, products, quotes, line items, custom objects, plus associations / pipelines / properties / owners / discover — as MCP tools.
```bash
# Register the server with Claude Desktop
hubspot mcp install --client claude-desktop
# Or Claude Code (user-level)
hubspot mcp install --client claude-code
# Or project-level Claude Code
hubspot mcp install --client claude-code --project
```
The `install` command merges a `hubspot` entry into the target client's MCP config; run with `--dry-run` first to preview. After restarting the client, the `hubspot` tools show up next to the client's built-in tools.
Manual Claude Desktop config (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"hubspot": {
"command": "hubspot",
"args": ["mcp", "serve"],
"env": { "HUBSPOT_ACCESS_TOKEN": "pat-na1-…" }
}
}
}
```
Full tool catalog and troubleshooting: [documentation/docs/llm-integration/mcp.md](documentation/docs/llm-integration/mcp.md).
---
## 🐍 Integration Examples
### Python Agent
```python
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
```bash
#!/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
```json
{
"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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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`
```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
```bash
# Clone and build
git clone https://github.com/dipankar/hubspot-cli
cd hubspot-cli
cargo build --release
# Run tests (130+ tests)
cargo test
# Format and lint
cargo fmt && cargo clippy
# Install locally
cargo install --path .
```
---
## Security
- **Tokens are never logged**: Access tokens use `secrecy::SecretString` and are never written to logs or error output.
- **Account-isolated cache**: Cache directories are scoped by account hash to prevent cross-portal leakage.
- **Zero `unsafe` code**: The codebase contains no `unsafe` blocks.
- **Audited dependencies**: `cargo-deny` and `cargo-audit` run on every CI build.
See [SECURITY.md](SECURITY.md) for vulnerability reporting and disclosure policy.
---
## Contributing
Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on code style, testing, and the release process.
Quick checklist:
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
---
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
---
## License
MIT — see [LICENSE](LICENSE) for details.
---
<div align="center">
**Built for the AI-first era of software development.**
[GitHub](https://github.com/dipankar/hubspot-cli) · [npm](https://www.npmjs.com/package/hubspot-cli) · [Crates.io](https://crates.io/crates/hubspot-cli) · [HubSpot API Docs](https://developers.hubspot.com/docs/api/overview)
</div>
