Running workflows from the CLI

The flux CLI registers workflow definitions, starts executions, checks status, and cancels runs without requiring you to write Python. Every other interface — SDK, REST API, MCP — delegates to the same underlying server. This page covers that end-to-end flow, along with the flux execution commands for querying historical runs.

Before running any of the commands below, make sure a Flux server is reachable. The CLI defaults to http://localhost:8000; pass --server-url <URL> to any command to connect to a different host.

Start a server and a worker

The CLI communicates with the server, not the workflow code directly. If you haven’t already started both services:

flux start server

In a separate terminal, start a worker. Workers require a bootstrap token so they can authenticate with the server. Generate one, then export it before starting:

export FLUX_WORKERS__BOOTSTRAP_TOKEN=$(flux server bootstrap-token)
flux start worker

Register a workflow

Before the server can execute a workflow, it must know about it. Registration parses a Python source file and records the workflow definition (name, version, source hash) in the server’s catalog:

flux workflow register my_workflow.py

Usage: flux workflow register [OPTIONS] FILENAME

  Register workflows from a file.

Options:
  -f, --format [simple|json]  Output format
  -cp-url, --server-url TEXT  Server URL to connect to.

Each call to register bumps the workflow’s version. Run it whenever you change the workflow code — the server keeps all prior versions and defaults new executions to the latest. To target a specific version when running, see the --version flag below.

Registration is idempotent for an unchanged file: re-registering the same source hash records a new version entry but leaves existing executions untouched.

Run a workflow

Once registered, start an execution with flux workflow run:

flux workflow run WORKFLOW_NAME INPUT

Usage: flux workflow run [OPTIONS] WORKFLOW_NAME INPUT

  Run the specified workflow.

Options:
  -m, --mode [sync|async|stream]  Execution mode (sync, async, or stream)
  -v, --version INTEGER           Specific workflow version to run (defaults
                                  to latest)
  -d, --detailed                  Show detailed execution information
  -cp-url, --server-url TEXT      Server URL to connect to.

INPUT is a positional argument containing the JSON-encoded input value. Pass a string literal, a JSON object, or null if the workflow takes no input:

# String input — note the inner quotes to produce a JSON string
flux workflow run greet '"world"'

# Structured input as a JSON object
flux workflow run ingest '{"source": "s3://my-bucket", "batch_size": 500}'

# No input
flux workflow run daily_report 'null'

Execution modes

The --mode flag controls how the CLI waits for the result:

Mode	Behaviour
`async` (default)	Returns immediately with the execution ID. The workflow runs in the background.
`sync`	Blocks until the workflow reaches a terminal state, then prints the result.
`stream`	Streams task-level events to stdout as they occur, then prints the final result.

Use async when you want to fire and track progress separately. Use sync for short workflows in scripts where you need the result inline. Use stream when you want live task-level visibility without polling.

# Async — get the execution ID back immediately
flux workflow run process_batch '{"items": 1000}'

# Sync — block until done
flux workflow run generate_report '"Q1"' --mode sync

# Stream — watch events in real time
flux workflow run etl_pipeline '{"date": "2026-01-01"}' --mode stream

Pin a specific version

By default, the latest registered version runs. To run an older version explicitly:

flux workflow run ingest '{"source": "s3://my-bucket"}' --version 3

This is useful when rolling back to a known-good version before a re-register corrects a regression.

Check execution status

After an async run, use the execution ID printed by the CLI to check status:

flux workflow status WORKFLOW_NAME EXECUTION_ID

Usage: flux workflow status [OPTIONS] WORKFLOW_NAME EXECUTION_ID

  Check the status of a workflow execution.

Options:
  -d, --detailed              Show detailed execution information
  -cp-url, --server-url TEXT  Server URL to connect to.

Example:

flux workflow status ingest 005d4b2f8a3c1e9b

The output shows the current execution state (RUNNING, COMPLETED, FAILED, CANCELLED) and the final output when the workflow has finished. Add --detailed to include the per-task event log — useful when diagnosing a failure or auditing task-level timings:

flux workflow status ingest 005d4b2f8a3c1e9b --detailed

Cancel a running execution

To stop a workflow that is currently running:

flux workflow cancel WORKFLOW_NAME EXECUTION_ID

Usage: flux workflow cancel [OPTIONS] WORKFLOW_NAME EXECUTION_ID

  Cancel a running workflow execution.

Options:
  -cp-url, --server-url TEXT  Server URL to connect to.

Example:

flux workflow cancel ingest 005d4b2f8a3c1e9b

The server transitions the execution to CANCELLING, signals the worker, and the execution reaches CANCELLED once the worker unwinds. Cancelling an already-finished execution returns an error.

List executions

The flux execution list command queries across all workflows. It supports filtering by workflow name, namespace, and state:

flux execution list

Usage: flux execution list [OPTIONS]

  List workflow executions.

Options:
  -w, --workflow TEXT         Filter by workflow reference (namespace/name or
                              bare name)
  -n, --namespace TEXT        Filter by namespace
  -s, --state TEXT            Filter by execution state (e.g., RUNNING,
                              COMPLETED, FAILED)
  -l, --limit INTEGER         Maximum number of results
  -o, --offset INTEGER        Number of results to skip
  -f, --format [simple|json]  Output format (simple or json)
  -cp-url, --server-url TEXT  Server URL to connect to.

Common filtering patterns:

# All executions for a specific workflow
flux execution list --workflow ingest

# Namespaced reference
flux execution list --workflow billing/invoice

# Only executions that are still running
flux execution list --state RUNNING

# Recent failures, most recent 20
flux execution list --state FAILED --limit 20

# Machine-readable JSON for scripting
flux execution list --workflow ingest --format json

The --offset and --limit flags support pagination when the list is long.

Inspect a single execution

To retrieve full details for one execution by ID:

flux execution show EXECUTION_ID

Usage: flux execution show [OPTIONS] EXECUTION_ID

  Show details of a specific execution.

Options:
  -d, --detailed              Show detailed execution information
  -cp-url, --server-url TEXT  Server URL to connect to.

Example:

flux execution show 005d4b2f8a3c1e9b

# Full event log (task start/complete times, outputs, errors)
flux execution show 005d4b2f8a3c1e9b --detailed

flux execution show exposes everything the server knows about an execution: state transitions, task events, error messages, and the final output. Use --detailed when a task failed and you want the exact exception.

Putting it together: a typical CLI session

# 1. Register after editing the workflow file
flux workflow register pipeline.py

# 2. Start an async execution
flux workflow run pipeline '{"date": "2026-01-01"}'
# → prints execution_id: 005d4b2f8a3c1e9b

# 3. Check status while it runs
flux workflow status pipeline 005d4b2f8a3c1e9b

# 4. List all executions for this workflow to compare runs
flux execution list --workflow pipeline --limit 5

# 5. Inspect the full event log once it finishes
flux execution show 005d4b2f8a3c1e9b --detailed

What’s next

Running workflows from the SDK — trigger and track executions programmatically using workflow.run() and FluxClient.
Running workflows from the REST API — call the HTTP endpoints directly from any language or scripting environment.
Manual cancellation — cancellation in depth: what happens to in-flight tasks, cleanup hooks, and how to handle CancelledError in workflow code.
Workflow versioning — how Flux versions registered workflows and how to pin executions to a specific version.