Commands & Flags

Read a Flow

flowctl --instance <url> --sys-id <id> [auth] [flags]

Flag	Notes
--format <fmt>	full (default), text, tree, yaml
--values	Show configured input values per step
--inputs	Show action type input schemas (extra API calls)
--output json	JSON-wrapped output for scripting
--no-color	Disable ANSI colors (also respects NO_COLOR)
--debug	Print API calls to stderr

Export

flowctl --instance <url> --export <sys_id> [--with-uuid]

Flag	Notes
--with-uuid	Include identity metadata for the update workflow

Validate

flowctl --validate <file.yaml>

Offline. No ServiceNow connection needed.

Create

Pro

Requires the Pro binary.

flowctl --instance <url> --create <file.yaml> [auth] [--dry-run]

Flag	Notes
--dry-run	Print planned API calls without executing

Update

Pro

Requires the Pro binary.

flowctl --instance <url> --update <file.yaml> [auth] [--dry-run]

The YAML file must contain sys_id and _metadata from a --with-uuid export.

Editor

flowctl --editor <addr>

Starts the local YAML editor (validate, diagram, create/update) without the full server. Community edition.

Scaffold

flowctl --init [--init-type <type>] [--init-name <name>]

Flag	Notes
--init-type	flow (default) or subflow
--init-name	Flow name for the generated template

Server

Pro

Requires the Pro binary built with team tag.

flowctl --serve <addr> [--dev] [--public]

Flag	Notes
--dev	Skip embedded assets, use local dev server
--public	Public website mode (marketing pages + editor, no authenticated flows list)

Authentication

Pick one method. OAuth2 takes precedence when both are provided.

OAuth2 Client Credentials

flowctl --instance <url> --sys-id <id> \
  --client-id <id> --client-secret <secret>

Or via environment variables:

export SN_CLIENT_ID=<client_id>
export SN_CLIENT_SECRET=<client_secret>

Basic Auth

flowctl --instance <url> --sys-id <id> \
  --user <username> --pass <password>

Or password via environment:

export SN_PASSWORD=<password>

REST API

Pro

The REST API requires the server (--serve).

Method	Path	Notes
GET	/api/v1/flows	List flows on the connected instance
GET	/api/v1/flows/{sys_id}	Full flow details
GET	/api/v1/flows/{sys_id}/yaml	Export as YAML
POST	/api/v1/flows	Create from YAML body
PUT	/api/v1/flows/{sys_id}	Update from YAML body
POST	/api/v1/flows/validate	Validate YAML (offline)
POST	/api/v1/flows/diagram	Generate flow diagram from YAML
GET	/api/v1/samples	List sample YAML files
POST	/api/v1/auth/test	Test SN connection
GET	/healthz	Health check

Interactive API docs at /api/docs (Swagger UI). OpenAPI spec at /api/docs/spec.

Add ?with_uuid=true to the YAML export endpoint to include identity metadata.

License Management

flowctl activate <key>     # Activate a Pro/Team license on this machine
flowctl deactivate         # Remove license from this machine
flowctl license            # Show current license status

Self-Update

flowctl update             # Check for updates and install if available

Downloads are verified with ed25519 signatures when available.

Environment Variables

Authentication

Variable	Description
SN_CLIENT_ID	OAuth2 Client ID (alternative to --client-id)
SN_CLIENT_SECRET	OAuth2 Client Secret (alternative to --client-secret)
SN_PASSWORD	Basic Auth password (alternative to --pass)

Licensing

Variable	Description
FLOWCTL_LICENSE	License key (alternative to ~/.flowctl/license.key)

Display

Variable	Description
NO_COLOR	Disable colored output when set to any value