hscli

hscli is a powerful command-line interface (CLI) tool written in Go for managing HubSpot contacts. It provides a simple, efficient way to perform CRUD operations on your HubSpot contacts directly from your terminal, eliminating the need to navigate through the HubSpot web interface for routine contact management tasks.

Features • Installation • Usage • Documentation • Contributing

Why hscli Exists

Managing contacts in HubSpot through the web interface can be time-consuming, especially when you need to:

• Bulk update contact properties
• Quickly search and filter contacts
• Automate contact management workflows
• Integrate HubSpot operations into scripts and automation pipelines

hscli bridges this gap by providing a fast, scriptable interface to HubSpot's contact management capabilities, making it perfect for developers, sales operations teams, and anyone who prefers working from the command line.

Benefits

• ⚡ Fast: Direct API access means instant results without browser overhead
• 🔧 Scriptable: Integrate HubSpot operations into your automation workflows
• 📊 Flexible Output: Choose between human-readable tables or JSON for programmatic use
• 🎯 Focused: Streamlined interface for contact management without UI distractions
• 🔄 Extensible: Built with a modular architecture ready for future HubSpot object support
• 🛡️ Secure: Supports multiple authentication methods including environment variables

Installation

macOS

brew tap obay/homebrew-tap
brew install hscli

Windows

scoop bucket add obay https://github.com/obay/scoop-bucket
scoop install hscli

Linux

Debian/Ubuntu:

wget https://github.com/obay/hscli/releases/latest/download/hscli_linux_amd64.deb
sudo dpkg -i hscli_linux_amd64.deb

Red Hat/CentOS/Fedora:

wget https://github.com/obay/hscli/releases/latest/download/hscli_linux_amd64.rpm
sudo rpm -i hscli_linux_amd64.rpm

Other distributions:

wget https://github.com/obay/hscli/releases/latest/download/hscli_linux_amd64.tar.gz
tar -xzf hscli_linux_amd64.tar.gz
sudo mv hscli /usr/local/bin/
sudo chmod +x /usr/local/bin/hscli

Direct Downloads

📦 View All Releases | 🔍 Checksums

Pre-built binaries are available for:

• macOS: Intel (amd64) and Apple Silicon (arm64)
• Linux: amd64 and arm64
• Windows: amd64

Configuration

hscli requires a HubSpot API key to authenticate. Choose one of these methods:

1. Config file (recommended): Create ~/.hscli.yaml:

   api-key: YOUR_API_KEY

2. Environment variable:

   export HUBSPOT_API_KEY=YOUR_API_KEY

3. Command-line flag:

   hscli contacts list --api-key YOUR_API_KEY

Getting Your HubSpot API Key

1. Log in to your HubSpot account
2. Navigate to Settings → Integrations → Private Apps
3. Create a new private app or use an existing one
4. Ensure the app has the following scopes:
   • crm.objects.contacts.read
   • crm.objects.contacts.write
5. Copy the API key (starts with pat-)

Usage

Once configured, you can use hscli without specifying the API key each time.

List Contacts

# List first 100 contacts
hscli contacts list

# List with custom limit
hscli contacts list --limit 50

# List all contacts (paginated)
hscli contacts list --all

# Output as JSON
hscli contacts list --format json

List Properties

View all available contact properties:

hscli contacts properties

# Output as JSON
hscli contacts properties --format json

Create a Contact

# Basic contact
hscli contacts create \
  --email "john.doe@example.com" \
  --firstname "John" \
  --lastname "Doe"

# With lifecycle stage
hscli contacts create \
  --email "jane@example.com" \
  --firstname "Jane" \
  --lastname "Smith" \
  --lifecycle-stage "customer"

# With custom properties
hscli contacts create \
  --email "bob@example.com" \
  --firstname "Bob" \
  --properties "company=Acme Inc,phone=555-1234"

Update a Contact

# Update lifecycle stage
hscli contacts update CONTACT_ID --lifecycle-stage "customer"

# Update multiple properties
hscli contacts update CONTACT_ID \
  --firstname "John" \
  --lastname "Updated" \
  --properties "company=New Company,phone=555-9999"

Search/Query Contacts

# Search by email
hscli contacts query "email=john@example.com"

# Search by property
hscli contacts query "lifecyclestage=customer"

# Limit results
hscli contacts query "email=example" --limit 10

Delete a Contact

# Delete with confirmation
hscli contacts delete CONTACT_ID

# Skip confirmation prompt
hscli contacts delete CONTACT_ID --force

Examples

Bulk Update Lifecycle Stage

# List all leads and update them to customers
hscli contacts query "lifecyclestage=lead" --format json | \
  jq -r '.[] | .id' | \
  while read id; do
    hscli contacts update "$id" --lifecycle-stage "customer"
  done

Export Contacts to CSV

hscli contacts list --format json | \
  jq -r '.[] | [.id, .properties.email, .properties.firstname, .properties.lastname] | @csv' > contacts.csv

Find Contacts by Domain

hscli contacts list --format json | \
  jq '.[] | select(.properties.email | contains("@example.com"))'

Command Reference

Global Flags

• --api-key string: HubSpot API key (or set HUBSPOT_API_KEY env var)
• --config string: Config file path (default: $HOME/.hscli.yaml)
• -h, --help: Show help information

Contacts Commands

hscli contacts list

List all contacts.

Flags:

• -l, --limit int: Maximum number of contacts to retrieve (default: 100)
• -a, --all: Retrieve all contacts (paginate through all pages)
• -f, --format string: Output format - table or json (default: table)

hscli contacts properties

List all available contact properties.

Flags:

• -f, --format string: Output format - table or json (default: table)

hscli contacts create

Create a new contact.

Flags:

• -e, --email string: Email address
• -f, --firstname string: First name
• -l, --lastname string: Last name
• --lifecycle-stage string: Lifecycle stage (e.g., lead, customer)
• -p, --properties string: Additional properties (format: key1=value1,key2=value2)

hscli contacts update [contact-id]

Update an existing contact.

Flags:

• -e, --email string: Email address
• -f, --firstname string: First name
• -l, --lastname string: Last name
• --lifecycle-stage string: Lifecycle stage
• -p, --properties string: Additional properties (format: key1=value1,key2=value2)

hscli contacts query [search-query]

Search for contacts.

Flags:

• -l, --limit int: Maximum number of results (default: 100)
• -f, --format string: Output format - table or json (default: table)

Query Format:

• Property-based: property=value (e.g., email=john@example.com)
• Text search: text (searches in email field)

hscli contacts delete [contact-id]

Delete a contact.

Flags:

• --force: Skip confirmation prompt

Troubleshooting

Authentication Errors

If you see authentication errors:

1. Verify your API key is correct
2. Ensure your private app has the required scopes
3. Check that the API key hasn't expired

Rate Limiting

HubSpot has rate limits. If you encounter rate limit errors:

• Reduce the frequency of requests
• Use pagination (--limit) instead of --all for large datasets
• Implement delays in scripts

Property Not Found

If a property update fails:

1. Use hscli contacts properties to list available properties
2. Ensure property names match exactly (case-sensitive)
3. Check that the property type matches the value you're setting

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues, questions, or contributions, please open an issue on GitHub.

Roadmap

• Support for other HubSpot objects (Deals, Companies, etc.)
• Batch operations for bulk updates
• Advanced filtering and querying options
• Import/export functionality
• Interactive mode for easier exploration

---

Made with ❤️ for the HubSpot community