How It Works

flowctl is a single binary that talks directly to your ServiceNow instance. No middleware, no plugins on the SN side.

What it does

• Read any flow and render it as text, tree diagram, YAML, or JSON
• Export flows to portable YAML files for version control
• Validate YAML flow definitions offline
• Create flows from YAML definitions
• Update existing flows with incremental changes
• Publish flows through ServiceNow’s compilation pipeline

How it connects

flowctl uses ServiceNow’s standard platform APIs — the same ones Flow Designer uses. Authentication supports OAuth2 (Client Credentials Grant) or Basic Auth. Rate-limited responses are retried automatically.

Read / Export

1. Fetch — parallel API calls collect the flow record, steps, triggers, and variables
2. Build — raw records assembled into a structured model (step tree, data pills, configured values)
3. Render — output as text, tree, YAML, or JSON

Create

1. Parse — YAML parsed and validated
2. Resolve — pill references resolved, step identifiers assigned
3. Create — records created in ServiceNow with configured values
4. Publish — if status: published, the flow is compiled so it’s ready to run

Update

1. Fetch — current flow state retrieved from ServiceNow
2. Diff — structural comparison between the live flow and your YAML
3. Apply — only changed steps are modified (inserts, updates, deletes, reorders)

The diff is tree-aware — it handles container lifecycle (adding/removing else and catch blocks), step reordering, and parent changes.

No SN-side artifacts

flowctl doesn’t install anything on your ServiceNow instance. No custom APIs, no tables, no plugins, no update sets. All operations use standard platform APIs that already exist on every instance.