Using dry run to change workflows safely with Agent CLI

Before I wrote this blog, I started writing something a lot more ambitious. There's so much about Agent CLI that gets me excited, and I wanted to share all of it with you. In one breath. Err, one blog.

Lucky for me, I have a solid set of peers who keep my excitement in check. So while that first post may never see the light of day (RIP first draft), I promise to deliver a series of blogs that walk you through managing workflows with Agent CLI. This one focuses on how to safely change or delete your workflows using --dry-run.
There are two reasons I'm starting here:

First, the whole point of Agent CLI is its ability to handle repetitive tasks in bulk. That's exciting when you're working across a lot of records on a regular basis. But, for many builders, it makes the fear of breaking something very real. I want to show you the safe way to do it.

Second, if you're used to managing HubSpot workflows in the UI, you're used to a safety net. You get a confirmation message before you delete anything. With Agent CLI, commands run as text, through an AI agent, sometimes across dozens of workflows at once. And some of those changes can't be undone. Once you delete a workflow, it's gone.

That makes using --dry-run with Agent CLI not just recommended, but required. In fact, HubSpot makes sure you can't update or delete a workflow until you've completed a dry run.

In this post I'll focus on using dry run for workflows, but the same pattern applies to other destructive operations like bulk record updates, deletes, and merges.

Before you begin

This post assumes you already have Agent CLI installed and authenticated. If you don't, the first post in this series details setup.

For the latest installation instructions, authentication details, command syntax, and permission requirements, see HubSpot Agent CLI documentation.

Note that Agent CLI is currently in beta. For this reason, everything in this post should be practiced in a developer test account first. The safe experimentation guide covers how to set up a test account.

If you have an Enterprise account and want to test against something that mirrors your real setup, a standard sandbox account copies your production pipelines, properties, and workflows. This will be useful for the update and delete steps later in this post.

What is --dry-run and why is it important to use with Agent CLI?

A dry run shows you what a command is about to do, and then stops, so you can check it before anything actually changes.

Let’s say you're about to delete a bunch of records. Instead of deleting them right away, a dry run will tell you "here's the list of what I would delete" so you can check it's correct first.

This is extremely important when using Agent CLI because write operations like create, update, and delete act on your live CRM data. If you delete a workflow and want it back, you're rebuilding it from scratch, unless you saved a copy first.

The good news is you can't forget to do this. HubSpot won't let you update or delete a workflow without a dry run.

Once you successfully run it, the dry run hands you a digest (think of it like a receipt), and you pass that digest back to make the change happen.

You can find --dry-run documented in Agent CLI GitHub repo and Agent CLI skills library. Your agent already knows how to use it.

Safely editing or deleting workflows

Agent CLI’s best use case is for bulk updates. If you are updating or deleting multiple workflows, you can do so easily with one prompt.

Before we start making changes, you should remember two things:

1. Updates are a full replace, not a patch. If you send only the actions you want to change without including the enrollment trigger, the enrollment trigger gets wiped.
   
   
2. You cannot undo a workflow deletion through the API. Once it's gone, it's gone. The CLI doesn't have an undo command. This is why the CLI makes deletion deliberately inconvenient.
   
   

Editing an existing workflow

Let’s try a live experiment in your test account with one workflow first.

Quick heads up that you'll see me use workflow IDs throughout this post. I use IDs because they're unique. Names can be long, or so similar to each other that it's easy to grab the wrong one. That's a preference for caution, not a rule. You're welcome to use the workflow name instead, and the agent will still work.

To find a workflow's ID, open the workflow in HubSpot's workflow builder and look at your browser's URL. The number in the address listed after “flow” is the ID. You can also just ask your agent to list your workflows with their IDs.

Now back to the experiment

Ask your agent:

"I want to update workflow 67911056. Currently it creates a task, but I want to also add a step that sets the contact property 'last workflow action' to 'follow-up task created'.”

Here is what the agent does:

1. Fetches the current state
2. Shows you the current actions and where the new one will go
3. Modifies the JSON to add the new action
4. Runs the update with --dry-run first. Notice I didn’t ask for this in my prompt. HubSpot requires it for a change like this, so the agent has to.

The dry-run produces a digest. It proves you've seen the preview and gives you what you need to apply the change. Also, notice that the digest expires after 5 minutes. This prevents someone from dry-running something on Monday and accidentally applying it on Friday with stale assumptions.

Let’s try another experiment with bulk updates, which is where the CLI really shines. Let’s say you need to disable every workflow that hasn't been modified in 6 months:

Ask your agent:

"Find enabled workflows not modified in six months. Show the IDs, names, last-modified dates, and object types. Save their definitions, then prepare, but do not apply, a dry run to disable them. I’ll review the list first."

The agent lists all enabled workflows not modified in the last six months, and stages the change for your review without touching anything.

The same three-step pattern applies whether you update one workflow or ten: preview, digest, then confirm.

An important distinction: Last-modified ≠ Last used workflow.

A workflow’s last-modified date tells us when its definition changed, not whether it is being used or enrolling records. Agent CLI can identify workflows that have not been edited recently, but it cannot show enrollment history or usage. Treat the results as candidates for review, not automatic disablement. Before disabling an enabled workflow, verify its activity in the workflow editor.

Deleting workflows

Before you delete anything, I'd recommend always saving a copy first:

"Before deleting workflow 67911056, save its full definition to a file so I can recreate it if needed."

That way, if you need it back, your agent can recreate it from that file. It won't have the same workflow ID, but the logic will be preserved.

Now we can proceed safely with deleting this workflow.

Try this:

"Walk me through deleting workflow 67911056”

The dry-run output confirms the workflow ID and the exact confirm string you need to execute the deletion. It also includes the digest hash, similar to what we covered in the previous section for updating workflows.

For bulk cleanup: If you're about to delete multiple workflows, say, every disabled workflow with "follow-up" in the name then the same dry-run/digest/confirm pattern applies. Your agent will preview the full list, and wait for your explicit go-ahead.

Let’s try an experiment for a bulk cleanup.

Ask your agent:

"Find and save all workflows with “follow-up” in their name. Save their full definitions to a file so I can recreate it if needed. Then walk me through deleting all the workflows you find.”

The output confirms:

✅ Dry run passed

✅ Identified workflow names and IDs

✅ Digest to apply all four within next five minutes

Picking the right tool for the job

If you’re used to building workflows from scratch via automations -> workflow builder, here's a decision framework that can assist you with understanding which tool to use and when.

Start with Breeze Assistant when you want to draft a workflow from a description, get a recommendation for how to set something up, or understand what a workflow is doing.

Use the workflow builder UI when you're designing a single new workflow and want to see the visual flow as you build it. Use it for brainstorming.

Use Agent CLI when you're making the same type of change to multiple workflows, and you want a preview of every change before it happens.

In practice, you’ll find the best workflow is often hybrid. Use the workflow builder to understand and visually validate the automation. Then use Agent CLI when you need to perform bulk updates.