hubspot-cli 0.2.0

<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.*

[![Crates.io](https://img.shields.io/crates/v/hubspot-cli?style=for-the-badge&logo=rust&logoColor=white&color=orange)](https://crates.io/crates/hubspot-cli)
[![Downloads](https://img.shields.io/crates/d/hubspot-cli?style=for-the-badge&color=green)](https://crates.io/crates/hubspot-cli)
[![CI](https://img.shields.io/github/actions/workflow/status/dipankar/hubspot-cli/ci.yml?branch=main&style=for-the-badge&logo=github&label=CI)](https://github.com/dipankar/hubspot-cli/actions)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](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

</td>
</tr>
</table>

---

## 🚀 Quick Start

### Install

```bash
# 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 |

---

## 🐍 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 (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](LICENSE) for details.

---

<div align="center">

**Built for the AI-first era of software development.**

[GitHub](https://github.com/dipankar/hubspot-cli) · [Crates.io](https://crates.io/crates/hubspot-cli) · [HubSpot API Docs](https://developers.hubspot.com/docs/api/overview)

</div>