Your HubSpot workflows are finally code your AI tools can read.
HubSpot workflows have lived behind a click-to-configure canvas for years. The Automation v4 beta API changes that — every flow is now a JSON definition you can pull, edit, diff, and push back. Gremlin CLI is among the first tools built for that surface.
The practical effect: the AI tools your team already uses can finally read your real workflow state, propose concrete edits, and ship them back with revision locking, dry-run defaults, and automatic backups. No more models that can only describe what to click.
Changes detected
enrollmentCriteria: 3 filters added
actions: 2 updated, 1 added
revisionId: locked to 14
Workflows were locked in a canvas. Now they are code.
HubSpot shipped the Automation v4 API in beta to make Flows programmable. That changes the posture teams can take toward their workflows — from carefully-clicked artifacts to reviewable, version- controlled assets. Gremlin wraps the API with the lifecycle commands teams actually need.
Click, hope, repeat
- • Every workflow change is a UI session an admin has to remember how to retrace.
- • No diff, no code review, no rollback beyond screenshots and prayer.
- • AI tools can describe what should change — they cannot actually change it.
- • Bulk updates across twenty workflows take a week of clicking.
Pull, edit, diff, apply
- • Workflows are JSON files your team reviews like any other code.
- • Claude, Cursor, and other AI tools read real state and propose concrete edits.
- • Revision guards and automatic backups protect the portal from mistakes.
- • Bulk edits are scripted passes over a folder of JSON, not calendar weeks.
The round-trip loop, in four commands
List, pull, diff, apply. That is the full loop. Everything else — v3 ID resolution, revision locking, backups, dry-run — happens inside these commands, not as extra steps a human has to remember.
g-gremlin hubspot workflows ls
List
Inventory every Automation v4 workflow in the portal. Optional --show-ids pairs v4 IDs with the legacy v3 IDs teams already use in URLs and runbooks.
g-gremlin hubspot workflows pull <flow_id>
Pull
Write the full workflow definition to a JSON file on disk. Now your AI tools can read it. Accepts legacy v3 IDs and resolves them to v4 automatically.
g-gremlin hubspot workflows diff workflows/<id>.json
Diff
Compare the local file against the live portal. See exactly what will change before you ship anything back, in a reviewable JSON diff.
g-gremlin hubspot workflows apply workflows/<id>.json --yes
Apply
Push changes back to HubSpot. Default is dry-run — apply requires --yes. Revision IDs are locked to prevent clobbering UI edits made after your pull. A local backup of the remote workflow is written on every apply.
Safe to put in front of real workflows
Shipping workflow changes from a terminal sounds scary. The defaults make it boring. Every apply is a dry-run until you pass --yes, every remote state is backed up before being touched, and revision guards refuse to overwrite a workflow that an admin edited in the UI after your pull.
Dry-run by default
apply refuses to change the portal without an explicit --yes. Mistakes stay local until you mean it.
Revision ID guards
If someone edited the workflow in the HubSpot UI after your pull, apply will refuse until you re-pull or pass --force. No silent overwrites.
Automatic remote backup
Every apply writes the current remote workflow to workflows/_backup/<id>.json before making changes. Roll back with a single re-apply of the backup file.
v3-to-v4 ID resolution
Legacy v3 workflow IDs (the ones your team already pastes in Slack and docs) are resolved to v4 automatically. You do not have to hunt for the new ID.
This depends on HubSpot's Automation v4 beta
The commands on this page use HubSpot's Automation v4 (Flows) API, which is still in beta access. Your portal has to be granted that access by HubSpot before any of these calls will succeed. Reach out to your HubSpot account team if you have not been enrolled yet.
Operationally: enable the commands in the CLI with G_GREMLIN_HUBSPOT_AUTOMATION_BETA=1 in your shell. The CLI refuses to run these commands until that flag is set, so you do not accidentally hit a beta endpoint from a non-enrolled portal.
Why teams turn this on
Once workflows are JSON, a lot of problems that used to be “we will get to it next quarter” turn into “we can ship that tomorrow.”
Let AI tools actually edit workflows
Hand the pulled JSON to Claude, Cursor, or whatever assistant your team runs. The model can read the real workflow state, propose edits, and emit a modified file you diff and apply. No more AI that can only describe what to click.
Version-control critical automation
Commit workflow JSON to the same repo that holds the rest of your RevOps scripts. Code review changes. Roll back with git. Stop trying to reconstruct a broken workflow from memory.
Migrate and clean up in bulk
Pull every workflow, grep across them, refactor common patterns, and apply back. Touching twenty workflows consistently is a half-day in code and a week in the UI.
Audit what changed and when
Combined with the automatic backup, every apply leaves a before/after artifact. Downstream governance and compliance stop guessing what an admin shipped last Tuesday.
Frequently asked
Is this an AI-generated workflow builder?
No. Gremlin does not generate workflows from natural language on its own. What it does is make real workflow state code-editable. Your AI tools (Claude, Cursor, etc.) can then read the JSON, propose edits, and emit a modified file. Gremlin diffs and applies it with guards. The LLM proposes; Gremlin executes deterministically.
Do I need HubSpot's Automation v4 beta to use this?
Yes. The Automation v4 (Flows) API is in HubSpot's beta program. Your portal needs to be granted access before these commands will work. If you do not have beta access yet, contact your HubSpot account team. You also set G_GREMLIN_HUBSPOT_AUTOMATION_BETA=1 in your shell to enable the commands in the CLI.
What about the classic workflow IDs my team already uses?
Every command accepts legacy v3 workflow IDs and resolves them to v4 automatically on pull, diff, and apply. The old IDs your team has in Slack threads and internal docs continue to work.
Can I break a live workflow with this?
Fewer ways than the UI, actually. apply is dry-run by default and requires an explicit --yes. Revision IDs are locked, so a UI edit made after your pull will block an apply until you re-pull or pass --force. A backup of the live workflow is written to disk before any change. Rollback is applying the backup file.
How is this different from HubSpot Projects or the Node SDK?
HubSpot Projects is for building UI extensions and cards inside the HubSpot product. The Node SDK wraps individual API endpoints. Neither gives you a round-trip ls / pull / diff / apply loop over the Automation v4 Flows API with safety guards built in. That is the gap Gremlin fills.
Is Gremlin the only tool that does this?
Gremlin is among the first CLIs built for HubSpot's Automation v4 beta. HubSpot itself ships an SDK that can call the raw endpoints. What Gremlin adds is the workflow lifecycle around those endpoints: round-trip JSON, reviewable diffs, revision guards, automatic backups, and the v3-to-v4 resolution your team needs day to day.
Stop describing workflow changes. Start shipping them.
If your portal has Automation v4 access, the four commands above are all you need. If not, this is a good reason to ask your HubSpot account team about joining the beta.