HubSpot + g-gremlin: Frequently Asked Questions
Everything you need to know about managing HubSpot from the command line with g-gremlin. Properties, pipelines, snapshots, packs, safety, workflows, and more.
How do I manage HubSpot properties from the command line?
Define properties in a YAML file with type, field_type, group, and options. Run `hubspot props plan --spec properties.yaml` to preview changes, then `hubspot props apply --spec properties.yaml --yes` to apply. Supports create, update, and archive (with --allow-archive).
g-gremlin hubspot props plan --spec properties.yaml --json g-gremlin hubspot props apply --spec properties.yaml --yes --json
Can I version control my HubSpot configuration?
Yes. g-gremlin uses YAML and JSON spec files that you can commit to git. Snapshots export your portal config to files. Packs are directories with all specs — fully git-trackable with diff-friendly formats.
g-gremlin hubspot snapshot --out snapshots/baseline git add snapshots/ && git commit -m "baseline snapshot"
How do I enforce required fields in HubSpot without an admin?
Three mechanisms: (1) requiredProperties on custom objects via `objects apply`, (2) validation rules for format enforcement via `validations apply`, (3) stage gating + workflows for process compliance. Note: HubSpot's "required" varies by surface — standard object required toggles are UI-only.
g-gremlin hubspot validations apply --spec validations.yaml --yes --json g-gremlin hubspot objects apply --spec objects.yaml --yes --json
Is it safe to make bulk changes to HubSpot programmatically?
Yes. Every mutating command is dry-run by default. You must pass --yes to apply. Incompatible changes are blocked. pack apply captures before/after snapshots automatically. Batch outcomes track succeeded/failed/retryable separately.
# Dry-run first (no --yes) g-gremlin hubspot pack plan ./packs/q1_cleanup --json # Then apply with explicit confirmation g-gremlin hubspot pack apply ./packs/q1_cleanup --yes --json
How do I get a before/after audit trail of HubSpot changes?
Run `hubspot snapshot` before and after changes, then `hubspot compare-snapshots <before> <after>`. Or use `pack apply` which captures both automatically in artifacts/<timestamp>/.
g-gremlin hubspot snapshot --out snapshots/before # ... make changes ... g-gremlin hubspot snapshot --out snapshots/after g-gremlin hubspot compare-snapshots snapshots/before snapshots/after --json
What admin tasks can g-gremlin automate?
Infrastructure tasks: properties, pipelines, objects, lists, validations, and data ops. Strategy, content ops, email templates, and reporting dashboards still need human direction. Claude Code can help plan — you approve and apply.
# The admin automation loop 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_dir>
Does g-gremlin support HubSpot workflows?
Yes, as a beta feature. Set G_GREMLIN_HUBSPOT_AUTOMATION_BETA=1 to enable HubSpot Automation v4 support. Covers list, pull, diff, create, update, and delete with revision guards. Full GA is on the roadmap.
export G_GREMLIN_HUBSPOT_AUTOMATION_BETA=1 g-gremlin hubspot workflows ls --limit 100 --json g-gremlin hubspot workflows pull <flow_id> --output flow.json
What HubSpot objects does g-gremlin support?
Standard objects: contacts, companies, deals, tickets. Custom objects: full CRUD with associations. Pipelines for deals, tickets, and leads. Lists with any objectTypeId.
g-gremlin hubspot schema ls --refresh --json g-gremlin hubspot objects ls --json g-gremlin hubspot pipelines ls deals --json
How does g-gremlin handle HubSpot API rate limits?
Built-in pacing with "safe" (default) and "turbo" profiles. Auto-backoff with exponential retry on 429 errors. Batch sizes stay within HubSpot limits (100 for upserts, 500 for associations).
# Safe mode (default) — conservative pacing g-gremlin hubspot upsert contacts --csv records.csv --id-column email --apply # Turbo mode — faster, still within limits G_GREMLIN_PACING=turbo g-gremlin hubspot upsert contacts --csv records.csv --id-column email --apply
Can I use g-gremlin with Claude Code or ChatGPT to manage HubSpot?
Yes. g-gremlin outputs structured JSON (--json flag) designed for AI consumption. Claude Code can generate YAML specs, run pack plan, review output, and execute pack apply. All commands follow the plan-then-apply pattern that AI agents handle well.
# Claude Code can run these in sequence: g-gremlin hubspot pack plan ./packs/update --json # AI reviews JSON output, then: g-gremlin hubspot pack apply ./packs/update --yes --json
What OAuth scopes does my HubSpot Private App need?
Run `hubspot pack doctor` to check. Common scopes: crm.schemas.contacts.read/write, crm.schemas.deals.read/write, crm.objects.deals.write, crm.lists.read/write. Doctor tells you exactly what's missing.
g-gremlin hubspot doctor --json # Output includes: # ✓ crm.schemas.contacts.read # ✓ crm.schemas.contacts.write # ✗ crm.lists.write ← MISSING
How do I manage multiple HubSpot portals (prod vs sandbox)?
Named profiles store portal ID, domain, timezone, and verification status per portal. Connect each portal once, then switch with `hubspot auth use`. The `hubspot auth list` command shows all profiles with portal metadata. Packs are portable — the same YAML applies to any portal.
# Connect production g-gremlin hubspot connect --access-token pat-na1-prod-token # Connect sandbox g-gremlin hubspot connect --access-token pat-na1-sandbox-token --profile sandbox # See all profiles g-gremlin hubspot auth list # * production portal:12345678 acme.hubspot.com # sandbox portal:87654321 acme-sandbox.hubspot.com # Switch g-gremlin hubspot auth use sandbox
What happens if a g-gremlin command fails mid-execution?
Batch outcomes are tracked: succeeded records stay, failed records are reported, retryable failures are flagged. For pack apply, the before_snapshot is already captured so you can compare what changed vs. what didn't.
# After a partial failure, check what applied: g-gremlin hubspot compare-snapshots artifacts/20260127/before_snapshot snapshots/current --json # Output shows exactly which items succeeded vs. failed
How do I export HubSpot list membership to CSV?
Run `hubspot lists members <list_id> --output members.csv --limit 1000`. Exports list_id, record_id, and membership_timestamp. Use --limit to control how many records to export.
g-gremlin hubspot lists members 42 --output members.csv --limit 1000 # Output: members.csv with columns: list_id, record_id, membership_timestamp
What is a g-gremlin "pack" and how does it work?
A pack is a directory with a pack.yaml config plus spec files (properties.yaml, validations.yaml, pipeline JSON, list JSON, etc.). Run `pack init` to scaffold, edit specs, `pack plan` to preview, `pack apply` to execute with automatic before/after snapshots and receipts.
g-gremlin hubspot pack init ./packs/onboarding # Edit specs in ./packs/onboarding/ g-gremlin hubspot pack plan ./packs/onboarding --json g-gremlin hubspot pack apply ./packs/onboarding --yes --replan --json
How do I query HubSpot from the command line?
Use `hubspot query <object_type>` with `--where` for simple equality filters or `--filter-json` for native HubSpot filterGroups. Output as JSON to stdout or CSV to a file. Useful for ad-hoc debugging and AI-driven investigations.
# Simple equality filter g-gremlin hubspot query contacts --where "[email protected]" --json # Complex filter from JSON file g-gremlin hubspot query deals --filter-json filters.json --properties dealname,amount --out results.csv # Count all contacts g-gremlin hubspot query contacts --limit 0 --json
How do I validate my HubSpot changes after applying a pack?
Define smoke assertions in your pack.yaml (property_exists, pipeline_has_stages, list_exists, workflow_exists). Run `hubspot smoke <pack_dir>` after apply. Exit code 1 on failure — CI-friendly. You can also enable smoke_after_apply in pack.yaml options for automatic post-apply verification.
# Run smoke tests against your pack g-gremlin hubspot smoke ./packs/onboarding --json # [PASS] property_exists: contacts.partner_source # [PASS] pipeline_has_stages: deals/12345 (stage_a, stage_b) # [FAIL] list_exists: 67890
How do I check for config drift across all pack components?
Run `hubspot drift <pack_dir>` to see a summary of all changes detected across properties, pipelines, lists, objects, validations, and workflows. Components not in your pack.yaml are marked as skipped. Use `--json` for machine-readable output.
g-gremlin hubspot drift ./packs/onboarding --json # Drift Report: onboarding # -------------------------------------------------- # properties 3 change(s) # pipelines clean # lists 1 change(s) # validations skipped (not included in pack.yaml) # -------------------------------------------------- # Total changes: 4
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.