hubspot-cli-setup

HubSpot CLI setup (Brainforge)

Version: 1.0
Date: April 1, 2026

Purpose

Use the official HubSpot CLI for developer-platform work: projects, apps, CMS assets, secrets, sandboxes, and account management. See the CLI command reference.

This is complementary to CRM REST API automation (notes, deals, properties) documented in hubspot-api-setup.md.

Install (repo-local, recommended)

Global npm install -g @hubspot/cli can fail with permissions. This repo pins the CLI under tools/hubspot-cli/.

npm install --prefix tools/hubspot-cli

Details: tools/hubspot-cli/README.md.

Authenticate

The CLI writes ~/.hscli/config.yml on your machine. It is not stored in the repository.

1. Run:

   cd tools/hubspot-cli && npx hs account auth

2. Follow prompts to create a Personal Access Key in HubSpot and paste it when asked. Official flow: Install the CLI → Authenticate.

3. Optional non-interactive auth if the key lives in 1Password:

   cd tools/hubspot-cli && npx hs account auth --personal-access-key "$(op read 'op://VAULT/ITEM/field')"

Never commit Personal Access Keys or paste them into knowledge/ or standards/.

Verify

cd tools/hubspot-cli && npx hs doctor
npx hs account list

Credentials: CLI vs API token

Mechanism	Typical use
Personal Access Key (hs account auth)	CLI: projects, CMS, app deploy, hs open, etc.
Private App access token (HUBSPOT_ACCESS_TOKEN)	REST API / tools/hubspot-api-service: CRM reads/writes, notes, deal updates

You may need both for different tasks.

See also

• hubspot-api-setup.md — REST API and activity logging
• HubSpot CLI install