Workflows

A workflow is a saved, ordered recording of HarborClient activity that you can replay. Record a session — open requests, edit drafts, send HTTP, switch environments, and (in the desktop app) open tabs, pages, or workspaces — then play it back with optional delays, gapless timing, and script-driven jumps.

Workflows are not the same as a collection run (which walks every saved request in collection or folder order) or a workspace (which restores a set of open tabs). Use a workflow when the sequence itself matters: which request loads next, which environment is active, and what draft changes happen between sends.

Why use workflows

Goal	How workflows help
Multi-step scenarios	Encode login → authenticated call, checkout flows, or any path that needs more than “run the folder”
Environment smoke checks	Activate Env A, send a health check, switch to Env B, send again — then replay or run from CI
Demos and repros	Capture exactly what you did in the UI and play it back without retyping
Branching during playback	Use request scripts to jump or skip actions based on status codes or variables
Portable run logs	Inspect results in the app, auto-export JSON from Settings, or write exports from the CLI

Concepts

Term	Meaning
Workflow	Named saved recording (uuid, name, actions, timing, optional reserved variables)
Action	One step in the recording: a type such as request.send or environment.activate, plus a payload
Recording	Live capture of allowlisted activity into a session until you stop and save
Playback / run	Replaying actions in the GUI or headlessly from the CLI
Gapless	GUI option: ignore recorded wall-clock gaps and start each step as soon as the previous finishes (default during playback)
Delay (delayMs)	Pause between consecutive actions during playback
Run results	Log of actions in exact execution order (including jumps); open from the run dialog or write to disk
Workflow export	Definition file (harborclientExport: "workflow") — the recording itself
Workflow-run export	Results file (harborclientExport: "workflow-run") — what happened on a completed run

Action types

Action	GUI	CLI (headless)	Notes
request.load	Yes	Yes	Opens a saved request by id
request.draft	Yes	Yes	Applies editor draft patches before send
request.send	Yes	Yes	Full HTTP send (scripts, cookies, auth)
request.save	Yes	Skipped	Persist request changes
request.create	Yes	Skipped	Create a new request
request.cancel	Yes	Skipped	Cancel an in-flight send
environment.activate	Yes	Yes	Activate or clear the active environment
page.open	Yes	Skipped	Open an app page
workspace.open	Yes	Skipped	Open a workspace
tab.activate / tab.new / tab.close / tab.closeAll	Yes	Skipped	Tab chrome only

Prefer load / draft / send / environment actions when you also want the same workflow to run from the command line.

Record a workflow

1. In the sidebar, find the Workflows section.
2. Click Record workflow (the + control in the section header).
3. In the Record workflow dialog, click Record.
4. Use HarborClient as usual: open saved requests, edit the draft, send, switch environments, and so on. Each allowlisted action is appended to the session.
5. Click Stop, then Save, and enter a name (the default is Untitled workflow).

Saved workflows appear under Workflows with a duration summary. Row menu Copy ID copies the workflow UUID (useful for scripts and CLI).

Run a workflow (GUI)

1. Click a workflow name in the sidebar. HarborClient opens a compact Running workflow dialog.
2. Click Play to start playback. Use Stop to halt early.
3. When the run finishes, click Results to open a Results: … tab. Actions appear in execution order; click a row for JSON detail (request/response, headers, cookies, tests, timing, and hc.data when present).

During playback you can adjust Delay (milliseconds between actions) and toggle Gapless. Gapless ignores the original recorded gaps so the run advances as soon as each step completes.

Edit a workflow

Open the workflow row menu → Edit to open the timeline editor:

Control	Purpose
Seek / play / stop	Scrub and preview playback
Rewind / fast-forward / restart	Jump along the timeline
Delay / Gapless	Same timing controls as the run dialog
Move / delete	Reorder or remove actions
Edit action JSON	Change an action’s payload
Rename / Save	Update the workflow name and persist edits

Export and results files

Action	How
Export definition	Workflow row menu → Export — saves a workflow JSON envelope
Auto-export run results	File → Settings → General → Workflow results directory — when set, each completed GUI run writes workflow-yyyy-mm-dd-hh-mm-ss.json there
CLI export	harborclient workflow run "…" --export <dir> — see Run from the CLI

The Results tab keeps the last in-memory run for that workflow until another run overwrites it. Set a results directory or use CLI --export when you need durable files.

There is no first-class Import flow for workflow definition exports in the sidebar yet. Definition exports are portable JSON for backup and tooling; create and edit workflows in the GUI.

Run from the CLI

The same harborclient binary that opens the desktop app also runs saved workflows headlessly. Workflows are read from the same Electron userData directory as the GUI (for example ~/.config/HarborClient on Linux, ~/Library/Application Support/HarborClient on macOS, and %APPDATA%\HarborClient on Windows).

harborclient workflow run "My Workflow"
harborclient workflow run <workflow-uuid> --stop-on-failure
harborclient workflow run "My Workflow" --export ./results
harborclient workflow run "My Workflow" --user-data /path/to/HarborClient

Option	Description
<name-or-uuid>	Case-insensitive workflow name or exact UUID from the local registry
--user-data <path>	Override the Electron userData directory
--stop-on-failure	Stop after the first failed request.send (transport error, HTTP ≥ 400, or failed hc.test)
--export <dir>	Write a workflow-run JSON export into that directory (collision-safe suffixes)

Headless playback always runs gapless and uses the workflow’s stored delayMs. It executes request.load, request.draft, request.send, and environment.activate. UI and persist actions (tab.*, page.open, workspace.open, request.save / create / cancel) are skipped. Progress lines print to the terminal; exit code 0 means success, 1 means not found, executor error, export failure, or send/test failures.

Create and edit workflows in the GUI first — the CLI only runs existing recordings. See Command line for ad-hoc requests and collection runs.

Scripts during workflows

Pre- and post-request scripts on sends still run during workflow playback, including hc.test assertions. While a workflow is playing a request.send action, scripts can control flow:

if (hc.response.code === 401) {
  hc.execution.workflowNextAction("aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee");
}

if (!hc.request.variables.get("runThisStep")) {
  hc.execution.workflowSkipAction();
}

API	Effect
hc.execution.workflowNextAction(id)	After this action, jump to the action with that UUID; unknown UUID falls through to the next step
hc.execution.workflowSkipAction()	Skip the rest of this action (in pre-request, also skips HTTP and post-request scripts)
hc.info.workflowId	UUID of the workflow being played; empty outside a workflow
hc.info.workflowActionId	UUID of the current action; empty outside a workflow
hc.info.workflowActionIteration	0-based action index; -1 outside a workflow

Copy action UUIDs from the timeline editor when wiring jumps. Full signatures live under Request scripts — hc.execution.

Recipes

These hello-world recipes use HarborClient’s public echo service so you do not need a private API. Substitute your own requests once the pattern is clear.

Recipe 1 — Record and replay a single send

1. Create a collection (or use an existing one). Add a GET request to https://echo.harborclient.com and File → Save Request (or Cmd/Ctrl+S).
2. Sidebar Workflows → Record workflow → Record.
3. Open the saved echo request from the sidebar (records request.load), then click Send (records request.send).
4. Stop → Save → name it Echo hello.
5. Click Echo hello in the sidebar → Play. When it finishes, open Results and confirm the send succeeded.

You now have a minimal replayable workflow: load a known request, send it, inspect the outcome.

Recipe 2 — Environment switch smoke

1. In Environments, create two environments — for example Echo A and Echo B. Optionally set a variable such as label to A and B so responses are easy to tell apart in scripts later. See Environments.
2. Reuse (or create) a GET https://echo.harborclient.com request. Save it.
3. Record workflow:
   • Activate Echo A (click it in the Environments sidebar or use the TabBar dropdown).
   • Open the echo request and Send.
   • Activate Echo B.
   • Send again.
4. Stop → Save → name it Echo env smoke.
5. Replay from the sidebar. Confirm both sends appear in Results and that environment activate actions sit between them.

This recording uses only CLI-friendly actions (environment.activate, request.load, request.send), so the same workflow works from the terminal in Recipe 3.

Recipe 3 — Run from the terminal

1. Complete Recipe 1 or Recipe 2 so a workflow exists in your local HarborClient data.
2. In a terminal, run:

harborclient workflow run "Echo hello" --export ./results

Or for the env smoke workflow with fail-fast:

harborclient workflow run "Echo env smoke" --stop-on-failure --export ./results

3. Confirm exit code 0 and that a workflow-run JSON file appears under ./results.
4. In CI, point --user-data at the machine’s HarborClient data directory (or a prepared copy) that already contains the saved requests and workflow:

harborclient workflow run "Echo env smoke" \
  --user-data "$HC_USER_DATA" \
  --stop-on-failure \
  --export ./artifacts

Requests referenced by request.load must still exist in that userData — deleting or re-saving with a new id breaks playback.

Limitations

• Create and edit in the GUI — the CLI only runs saved workflows.
• Headless ≠ full GUI replay — tab, page, workspace, and some request persist actions are skipped; prefer load/draft/send/environment for portable workflows.
• Requests must still exist — request.load resolves by saved request id; missing requests fail playback.
• Workflow variables — stored and exported for future parameterization; the product UI does not apply them yet.
• No first-class definition import — Export writes a workflow envelope; there is no sidebar Import for workflows yet.
• --stop-on-failure is CLI-oriented — the GUI run dialog does not expose the same flag.
• Branching needs action UUIDs — unknown workflowNextAction targets fall through to the next linear step.
• Not a collection substitute — to run every request in a folder, use the collection runner or harborclient run <collection>.

What's next

• Making requests — build, save, and send the requests your workflows load
• Environments — activate named variable sets during a recording
• Request scripts — hc.execution.workflowNextAction, workflowSkipAction, and hc.info
• Testing — assertions that run on workflow sends
• Command line — ad-hoc requests, collection runs, and workflow runs
• Collections — collection runs vs recorded workflows