CLI Reference

g-gremlin HubSpot CLI Reference

Every command, flag, and recipe for managing HubSpot from the terminal. Properties, pipelines, objects, lists, validations, workflows, snapshots, and packs.

Start HubSpot Trial Jump to Snapshots

Glossary Quick Start Auth Schema Properties Validations Objects Pipelines Lists Workflows Data Ops Merge & Dedup Engagements Exports Imports Associations Webhooks History Admin Snapshots Packs & Drift Safety Flags Env Vars Recipes

Key Concepts

Pack

A directory containing YAML/JSON specs for properties, pipelines, lists, validations, objects, and workflows. Represents a coordinated change set.

Snapshot

A point-in-time capture of your HubSpot portal's configuration (properties, pipelines, lists, workflows, custom objects). Read-only, no mutations.

compare-snapshots

Diffs two snapshots to produce a receipt showing what changed between them (added/removed/changed counts + per-item summaries).

--yes

The explicit confirmation flag required to apply any mutation. Without it, all commands are dry-run.

Beta workflows

HubSpot Automation v4 support, enabled via G_GREMLIN_HUBSPOT_AUTOMATION_BETA=1. Includes revision guards. GA on roadmap.

Doctor

Pre-flight check that validates your HubSpot Private App token, required OAuth scopes, and pack structure before you run anything.

Profile

A named connection to a HubSpot portal, storing token, API version, portal ID, domain, timezone, and verification status. Managed via auth list / auth use.

destructive.yaml

Manifest file listing approved destructive operations (property archives, stage deletes, workflow deletes). Dual-key safety: manifest entry AND allow_* flag both required.

Quick Start

Three commands to go from zero to your first portal snapshot.

quick start

# 1. Connect your HubSpot Private App token

$ g-gremlin hubspot connect --access-token pat-na1-xxxxx

✓ Token stored in keychain

# 2. Validate credentials and scopes

$ g-gremlin hubspot doctor --json

✓ Token valid

✓ Portal: acme-corp (ID: 12345678)

✓ crm.schemas.contacts.read

✓ crm.schemas.contacts.write

✓ crm.schemas.deals.read

✓ crm.schemas.deals.write

✓ crm.objects.deals.write

✓ crm.lists.read

✓ crm.lists.write

... 5 more scopes OK

# 3. Take your first snapshot (read-only)

$ g-gremlin hubspot snapshot --out snapshots/first_look

✓ Captured: 47 properties · 3 pipelines · 12 lists · 2 custom objects

Connection & Auth

g-gremlin hubspot connect --access-token <PAT> [--profile <name>]Store HubSpot Private App Token. Runs doctor automatically to verify and capture portal metadata.

g-gremlin hubspot auth listShow all saved profiles with portal ID, domain, and verification status

g-gremlin hubspot auth use <profile>Switch the active profile to a different portal

g-gremlin hubspot auth remove <profile>Delete a saved profile

g-gremlin hubspot validateQuick credential validation against the HubSpot API

g-gremlin hubspot doctor --jsonFull health check: credentials, scopes, and capabilities

g-gremlin hubspot whoami --jsonPortal ID, domain, and timezone for the connected account

g-gremlin hubspot open [--path <url_path>]Open the current portal in your browser. Use --path to override the default URL.

g-gremlin hubspot setup [--pack <dir>] [--full-beta] [--json]Print HubSpot Private App setup checklist with required scopes. Use --pack to scope to a specific pack.

g-gremlin hubspot oauth connect [--workspace-id <id>] [--no-browser]Start browser-based OAuth flow for HubSpot

g-gremlin hubspot oauth status --jsonCheck server-side HubSpot OAuth status

Schema

g-gremlin hubspot schema sync --jsonCache HubSpot schema locally for offline inspection

g-gremlin hubspot schema ls --refresh --jsonList all objects (standard + custom) in the portal

g-gremlin hubspot schema show <object_type> --refresh --jsonShow all properties for a specific object type

Properties

g-gremlin hubspot props list [object_types...] --match <pattern> --jsonList available properties for object types (defaults: contacts companies deals). Filter with --match.

g-gremlin hubspot props plan --spec properties.yaml --jsonPreview property changes (DRY-RUN) — shows creates, updates, and archives

g-gremlin hubspot props drift --spec properties.yaml --jsonAlias for plan — detect drift between spec and live portal

g-gremlin hubspot props apply --spec properties.yaml --yes --jsonApply property changes — requires --yes to execute mutations

Key flags: --allow-archive, --refresh, --match

Validations

g-gremlin hubspot validations plan --spec validations.yaml --jsonPreview validation rule changes (regex, enum, phone, email)

g-gremlin hubspot validations apply --spec validations.yaml --yes --jsonApply validation rules — requires --yes to execute

Custom Objects

g-gremlin hubspot objects ls --jsonList all custom objects in the portal

g-gremlin hubspot objects pull <object_type_id> --output out.jsonExport a custom object schema to a local JSON file

g-gremlin hubspot objects plan --spec objects.yaml --jsonPreview custom object changes (DRY-RUN)

g-gremlin hubspot objects apply --spec objects.yaml --yes --jsonApply custom object changes — requires --yes to execute

Pipelines

g-gremlin hubspot pipelines ls <object_type> --jsonList pipelines for deals, tickets, or leads

g-gremlin hubspot pipelines pull <object_type> <pipeline_id> --output spec.jsonExport a pipeline and its stages to a local JSON file

g-gremlin hubspot pipelines drift --spec spec.json --jsonPreview pipeline changes — shows stage additions, updates, removals

g-gremlin hubspot pipelines apply --spec spec.json --yes --jsonApply pipeline changes — requires --yes; deletions require --allow-delete

Key flags: --allow-delete

Lists

g-gremlin hubspot lists ls --limit 500 --jsonList all HubSpot lists with IDs, names, and types

g-gremlin hubspot lists pull <list_id> --output spec.jsonExport a list's definition and filters to a local JSON file

g-gremlin hubspot lists members <list_id> --output members.csv --limit 1000Export list membership to CSV (list_id, record_id, membership_timestamp)

g-gremlin hubspot lists diff --spec spec.json --jsonPreview list filter changes (DRY-RUN)

g-gremlin hubspot lists apply --spec spec.json --yes --jsonApply list changes — requires --yes to execute

g-gremlin hubspot lists add-members <list_id> --csv contacts.csv --column record_id --yesAdd contacts to a static (MANUAL/SNAPSHOT) list from CSV or --ids

g-gremlin hubspot lists remove-members <list_id> --csv contacts.csv --column record_id --yesRemove contacts from a static list from CSV or --ids

Workflows (Beta)

BETA

Requires G_GREMLIN_HUBSPOT_AUTOMATION_BETA=1 environment variable.

g-gremlin hubspot workflows ls --limit 100 --jsonList HubSpot Automation v4 flows

g-gremlin hubspot workflows pull <flow_id> --output flow.jsonExport a workflow definition to a local JSON file

g-gremlin hubspot workflows diff --spec flow.json --jsonPreview workflow changes with revision guard check

g-gremlin hubspot workflows apply --spec flow.json --yes --jsonApply workflow changes — requires --yes; use --force to skip revision check

g-gremlin hubspot workflows delete <flow_id> --yes-reallyDelete a workflow — requires --yes-really (destructive intent gate)

Key flags: --force (skip revision check)

Data Operations

g-gremlin hubspot query <object_type> --where "[email protected]" --jsonSearch any object type via the HubSpot Search API with --where (EQ only) or --filter-json for native filterGroups

g-gremlin hubspot query <object_type> --filter-json filters.json --properties prop1,prop2 --out results.csvQuery with native HubSpot filterGroups JSON and export to CSV

g-gremlin hubspot pull <object_type> --properties email,firstname --limit 1000 --output contacts.csvPull records to CSV with selected properties

g-gremlin hubspot upsert <object_type> --csv records.csv --id-column email --applyUpsert records from CSV — requires --apply to execute

g-gremlin hubspot associate --from-object contacts --to-object companies --csv mappings.csv --applyCreate associations between objects from CSV mapping

g-gremlin hubspot dissociate --from-object contacts --to-object companies --csv mappings.csv --applyRemove associations between objects from CSV mapping

Merge & Dedup

g-gremlin hubspot merge-plan <object_type> --key-column email --out plan.json --json-summaryBuild a merge plan from CSV or live search results. Groups duplicates by key field and picks a primary record.

g-gremlin hubspot merge-plan <object_type> --where "domain=acme.com" --key-column domain --keep oldest-created --out plan.json

Build merge plan from live search with winner strategy (first, oldest-created, newest-activity)

g-gremlin hubspot merge-apply-plan --plan plan.json --apply --json-summaryApply a merge plan (dry-run by default). Supports --resume with --state-file for interrupted runs.

g-gremlin hubspot merge <object_type> --primary-id 123 --merge-id 456 --applyMerge two specific records of the same object type

Key flags: --keep (first|oldest-created|newest-activity), --auto-window-on-cap, --continue-on-error

Engagements

g-gremlin hubspot engagements pull --types emails,calls,meetings --output-dir ./engagements --json-summaryPull engagement data and write normalized fact/bridge CSVs. Auto-falls back to async export when capped.

Key flags: --since, --until, --limit, --properties, --auto-export-on-cap, --export-timeout

Exports (Async)

g-gremlin hubspot exports start --object contacts --properties email,firstname --jsonStart an async HubSpot export task. Supports VIEW or LIST export types.

g-gremlin hubspot exports status --id <export_id> --jsonCheck the status of an async export task

g-gremlin hubspot exports download --id <export_id> --out export.csv --wait --jsonDownload an export result file. Use --wait to poll until ready.

Key flags: --export-type (VIEW|LIST), --list-id, --format (CSV|XLS|XLSX), --timeout, --poll-interval

Imports (Native)

g-gremlin hubspot imports start --request-json config.json --file data.csv --wait --jsonStart a native HubSpot import. Use --wait to poll until complete.

g-gremlin hubspot imports status --id <import_id> --jsonCheck the status of an import

g-gremlin hubspot imports errors --id <import_id> --jsonGet row-level import errors. Use --include-warnings for warnings too.

g-gremlin hubspot imports cancel --id <import_id> --yes --jsonCancel an in-flight import — requires --yes

Association Labels & Limits

g-gremlin hubspot associations labels ls <from_type> <to_type> --jsonList association labels for an object pair

g-gremlin hubspot associations labels create <from_type> <to_type> --name <name> --label <label> [--inverse-label <label>] --apply

Create an association label (dry-run by default)

g-gremlin hubspot associations labels update <from_type> <to_type> --association-type-id <id> --label <label> --applyUpdate an association label

g-gremlin hubspot associations labels delete <from_type> <to_type> --association-type-id <id> --applyDelete an association label (dry-run by default)

g-gremlin hubspot associations limits ls <from_type> <to_type> --jsonList association limits for an object pair

g-gremlin hubspot associations limits set <from_type> <to_type> --input <category:type_id:max> --applyCreate or update association limits

Webhooks

g-gremlin hubspot webhooks subscriptions ls --app-id <app_id> --jsonList webhook subscriptions for a HubSpot developer app

g-gremlin hubspot webhooks subscriptions create --app-id <app_id> --event-type <type> --apply --jsonCreate a webhook subscription (dry-run by default)

g-gremlin hubspot webhooks subscriptions set-active --app-id <app_id> --subscription-id <id> --active --applyActivate or deactivate a webhook subscription

g-gremlin hubspot webhooks subscriptions delete --app-id <app_id> --subscription-id <id> --applyDelete a webhook subscription (dry-run by default)

Key flags: --dev-api-key, --property-name, --active/--inactive

Property History

g-gremlin hubspot history pull <object_type> --property lifecyclestage --id 123,456 --out history.csvPull propertiesWithHistory for specific records. Shows who changed what and when.

g-gremlin hubspot history pull <object_type> --property lifecyclestage,hs_lead_status --csv records.csv --id-column hs_object_id --json

Pull history for multiple properties from a CSV of record IDs

Key flags: --include-current, --archived, --continue-on-error, --id-property

Admin & Governance

g-gremlin hubspot admins users ls --jsonList HubSpot portal users (via owners endpoint). Use --include-archived for inactive users.

g-gremlin hubspot admins goals ls --limit 1000 --jsonList HubSpot goals with properties and status

g-gremlin hubspot admins goals pull <goal_id> --out goal.json --jsonExport a single goal record to a local file

Snapshots & Compare

g-gremlin hubspot snapshot --out snapshots/baseline --include-workflows --json-summaryCapture full portal config — properties, pipelines, lists, objects, workflows

g-gremlin hubspot compare-snapshots <dir_a> <dir_b> --jsonDiff two snapshots — added, removed, changed counts + per-item summaries

Key flags: --pipeline-object deals, --pipeline-ids, --list-ids, --workflow-ids, --include-list-members

Packs (Orchestration)

g-gremlin hubspot pack init <dir>Initialize a pack directory with pack.yaml, spec stubs, and destructive.yaml manifest

g-gremlin hubspot pack plan <dir> --jsonPlan all components in the pack (DRY-RUN). Includes destructive ops coverage report.

g-gremlin hubspot pack apply <dir> --yes --replan --jsonApply pack with automatic before/after snapshots and receipts

g-gremlin hubspot pack doctor <dir> --jsonValidate pack structure, spec files, and required scopes

g-gremlin hubspot drift <dir> [--json]Show drift across all pack components — clean, drifted, skipped, or error per component

g-gremlin hubspot smoke <dir> [--json]Run post-deploy smoke assertions defined in pack.yaml. Exit code 1 on failure (CI-friendly).

Safety Flags Reference

Flag	Commands	Effect
--yes	All apply commands	Required to execute mutations
--apply	upsert, associate, dissociate, merge, merge-apply-plan, associations, webhooks	Required to execute data operations and two-phase mutations
--allow-delete	pipelines apply	Permits stage deletions
--allow-archive	props apply	Permits property archival
--force	workflows apply	Skips revision ID check
--replan	pack apply	Replans if state has drifted
--yes-really	workflows delete	Destructive intent gate for irreversible operations
destructive.yaml	pack apply	Manifest listing approved destructive ops — dual-key with allow_* flags

Environment Variables

G_GREMLIN_HUBSPOT_ACCESS_TOKEN

HubSpot Private App token

G_GREMLIN_HUBSPOT_PROFILE

Override the active profile (e.g. "sandbox") without switching via auth use

G_GREMLIN_HUBSPOT_AUTOMATION_BETA

Set to 1 to enable workflow commands

example usage

$ export G_GREMLIN_HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxx

$ export G_GREMLIN_HUBSPOT_AUTOMATION_BETA=1

$ g-gremlin hubspot workflows ls --json

✓ 14 workflows found

Common Recipes

Update Properties

recipe — update properties

# 1. Edit your YAML spec

$ vim properties.yaml

# 2. Preview the plan

$ g-gremlin hubspot props plan --spec properties.yaml --json

⟳ Plan: +2 create · ~1 update · 0 archive

# 3. Apply

$ g-gremlin hubspot props apply --spec properties.yaml --yes --json

✓ Applied: 2 created · 1 updated · 0 archived

Add a Pipeline Stage

recipe — add pipeline stage

# 1. Pull existing pipeline

$ g-gremlin hubspot pipelines pull deals abc123 --output deal_pipeline.json

✓ Exported to deal_pipeline.json

# 2. Edit JSON — add your new stage

$ vim deal_pipeline.json

# 3. Preview changes

$ g-gremlin hubspot pipelines drift --spec deal_pipeline.json --json

⟳ Plan: +1 stage (Negotiation)

# 4. Apply

$ g-gremlin hubspot pipelines apply --spec deal_pipeline.json --yes --json

✓ Applied: 1 stage added

Audit Your Portal

recipe — portal audit

# 1. Run doctor

$ g-gremlin hubspot doctor --json

✓ Token valid · Portal: acme-corp · 12 scopes OK

# 2. Take a full snapshot

$ g-gremlin hubspot snapshot --out snapshots/audit --include-workflows --json-summary

✓ Captured: 47 properties · 3 pipelines · 12 lists · 14 workflows

# 3. Browse the captured files

$ ls snapshots/audit/

properties/ pipelines/ lists/ objects/ workflows/ summary.json

Full Pack Workflow

recipe — full pack workflow

# 1. Initialize a new pack

$ g-gremlin hubspot pack init ./packs/q1_cleanup

✓ Created: pack.yaml, properties.yaml, validations.yaml

# 2. Edit your specs

$ vim ./packs/q1_cleanup/properties.yaml

# 3. Validate the pack

$ g-gremlin hubspot pack doctor ./packs/q1_cleanup --json

✓ Pack structure valid · All scopes present

# 4. Plan everything

$ g-gremlin hubspot pack plan ./packs/q1_cleanup --json

⟳ Plan: +4 properties · ~2 pipeline stages · +1 validation

# 5. Apply with receipts

$ g-gremlin hubspot pack apply ./packs/q1_cleanup --yes --replan --json

✓ Applied. Snapshots: artifacts/20260127_143022/before · after

The 5-command loop — the signature g-gremlin workflow:

g-gremlin hubspot doctor

g-gremlin hubspot snapshot --out snapshots/baseline

g-gremlin hubspot pack plan <pack_dir>

g-gremlin hubspot pack apply <pack_dir> --yes

g-gremlin hubspot compare-snapshots snapshots/baseline <after_snapshot_dir>

Ready to Operate HubSpot Like Code?

30 days free. No credit card required. Start with a read-only snapshot — zero risk.

Start HubSpot Trial Run a Snapshot (read-only)