Hubspot Contacts

HubSpot Contacts (via hubspot CLI)

Drive HubSpot contact operations through the hubspot CLI. Every command emits a JSON envelope ({"success": true, "data": ...}) suitable for parsing.

Prerequisite: authentication

The CLI reads HUBSPOT_ACCESS_TOKEN (a HubSpot private-app token) from the environment. If a command returns exit code 3 with AUTH_ERROR, tell the user:

export HUBSPOT_ACCESS_TOKEN=

Multi-account users can pass --profile (reads [profiles.] from ~/.config/hubspot-cli/config.toml).

Canonical commands

| Intent | Command | | --- | --- | | List recent contacts | hubspot crm contacts list --limit 10 | | Paginate | hubspot crm contacts list --limit 50 --after | | Request extra properties | hubspot crm contacts list --properties phone,company,lifecyclestage | | Get by ID | hubspot crm contacts get 12345 | | Create from flags | hubspot crm contacts create --email jane@example.com --firstname Jane --lastname Doe | | Create from JSON | hubspot crm contacts create --properties '{"email":"jane@x.com","lifecyclestage":"lead"}' | | Update | hubspot crm contacts update 12345 --firstname Janet | | Delete (archive) | hubspot crm contacts delete 12345 --yes | | Simple search | hubspot crm contacts search --query "email:*@acme.com" --limit 25 | | Filtered search | hubspot crm contacts search --filter-groups '[{"filters":[{"propertyName":"lifecyclestage","operator":"EQ","value":"customer"}]}]' | | Batch create | hubspot crm contacts batch-create --inputs '[{"properties":{"email":"a@x.com"}},{"properties":{"email":"b@x.com"}}]' | | Discover properties | hubspot discover properties contacts |

Filter-group operators

Common operator values for --filter-groups: EQ, NEQ, GT, GTE, LT, LTE, BETWEEN, IN, NOT_IN, HAS_PROPERTY, NOT_HAS_PROPERTY, CONTAINS_TOKEN, NOT_CONTAINS_TOKEN. Filter groups are OR'd; filters within a group are AND'd.

Default vs custom properties

Only email, firstname, lastname come back by default. For anything else (phone, company, lifecyclestage, hs_lead_status, hubspot_owner_id, custom properties) pass --properties prop1,prop2,.... Use hubspot discover properties contacts to list every valid property name.

Output envelope

{
  "success": true,
  "data": { "id": "12345", "properties": { "email": "...", "firstname": "..." } },
  "paging": { "next_cursor": "abc", "has_more": true }
}

List endpoints put an array in data. Pagination: when paging.has_more is true, call again with --after .

Error codes (JSON error.code, exit code)

| Code | Exit | Action | | --- | --- | --- | | AUTH_ERROR | 3 | Tell the user to set HUBSPOT_ACCESS_TOKEN | | VALIDATION_ERROR / DUPLICATE_EMAIL | 5 | Show error.message; fix input | | NOT_FOUND | 6 | Contact ID doesn't exist or was archived | | RATE_LIMIT | 7 | Back off using error.retry_after_seconds | | SERVER_ERROR | 8 | Transient; retry once |

Required scopes

• Read: crm.objects.contacts.read
• Write: crm.objects.contacts.write
• Search: crm.objects.contacts.read

Tips for the agent

• Prefer search over list when the user describes a filter ("contacts in lifecycle stage customer"). list has no filtering.
• Always pass --limit when the user says "a few" / "some" to keep responses small.
• Use --output json-pretty only when showing the raw JSON to the user; use the default json when piping into jq or parsing.
• Never echo the access token back to the user.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dipankar
• Source: dipankar/hubspot-cli
• License: MIT

Install and usage instructions live in the source repository linked above.