Overview

What are Flows?¶

Flows are the core automation units in flowctl. A flow is a set of actions that execute in order, or as a dependency graph, with support for inputs, variables, approvals. Flows are defined using YAML/HUML files and can run locally or on remote nodes.

Flow Structure¶

Every flow consists of five main sections:

1. Metadata - Flow identification and configuration
2. Inputs - Parameters that users provide when triggering the flow
3. Actions - The actual tasks to execute
4. Schedules - List of cron schedules
5. Notifications - Event-based notifications to users or groups

Basic Flow Example¶

Here's a simple flow that greets a user:

metadata:
  id: hello_world
  name: Hello World
  description: A simple greeting flow
  allow_overlap: true

inputs:
  - name: username
    type: string
    label: Username
    description: Your name
    required: true
    validation: len(username) > 0

actions:
  - id: greet
    name: Greet User
    executor: docker
    variables:
      - username: "{{ inputs.username }}"
    with:
      image: docker.io/alpine
      script: |
        echo "Hello, $username!"
        echo "message=Welcome!" >> $FC_OUTPUT

Metadata¶

The metadata section defines the flow's identity and behavior:

metadata:
  id: my_flow # Unique identifier (alphanumeric + underscore)
  name: My Flow # Human-readable name
  description: Flow description
  namespace: default # Namespace for organization
  allow_overlap: true # Allow executions to overlap
  execution_mode: sequential # sequential (default) or dag

Execution Overlap¶

If allow_overlap is set to true in a flow, executions for that flow can overlap. This is false by default which prevents executions from running if there is already an execution in running / pending state.

Execution Mode¶

Actions run one after another by default. Setting execution_mode: dag lets each action declare what it waits for, so independent branches run in parallel. See Execution Modes.

Scheduling Flows¶

Flows can be scheduled using cron expressions.

inputs:
  - name: environment
    type: string
    default: "production" # Required for scheduled flows

schedules:
  - cron: "0 2 * * *" # Run daily at 2 AM
    timezone: Asia/Kolkata
    name: Nightly run # Optional label

The name is optional. It is worth setting on a flow with several schedules, since it is what the flow list shows next to the upcoming run.

User Schedules¶

You can also create your own schedules from the UI, separate from the ones defined in the flow YAML. These let you run the same flow on different schedules with different input values.

To enable this, add user_schedulable: true to your flow metadata:

metadata:
  id: my_flow
  name: My Flow
  user_schedulable: true

Once enabled, go to a flow's Schedule tab and click Add to create a schedule.

Scheduling a Flow for Later¶

When triggering a flow manually you can defer execution by enabling the Run Later toggle. Choose a date, time, and timezone. The flow is queued and starts at the specified time.

The timezone selector defaults to your browser's local timezone. You can search for any IANA timezone (e.g. America/New_York, Europe/Berlin).

Re-running an Execution¶

A finished execution can be run again with the same inputs from the Retry button on the execution page. This queues a fresh execution; the original is left as it is.

Re-running from an Action¶

If only part of a flow needs to run again, pick the action to start from instead of re-running the whole thing. On the execution page, use the re-run button on an action, either in the action list on the left or on the Pipeline tab. The selected action and everything downstream of it run again, while the actions before it keep their existing results and outputs.

What counts as downstream depends on the execution mode. In a sequential flow it is every action listed after the one you picked. In a dag flow it is every action that depends on it, directly or transitively.

Before anything starts, the confirmation dialog lists which actions will run.

Log Download¶

Execution logs can be downloaded as a raw .log file once an execution has completed, errored, or been cancelled. The download button is available on the execution detail page.

Duplicating a Flow¶

To create a copy of an existing flow, open the flow list, click the ... menu on any flow, and select Duplicate. The create form opens pre-filled with the original flow's metadata, inputs, actions, and notifications.

Next Steps¶

• Define Inputs
• Configure Actions
• Run actions in parallel with Execution Modes
• Set up Notifications
• Configure Remote Nodes
• Learn about Executors
• Explore Access Control