FlowFile

Configuration for a group of Flow CLI executables. The file must have the extension .flow, .flow.yaml, or .flow.yml in order to be discovered by the CLI. It's configuration is used to define a group of executables with shared metadata (namespace, tags, etc). A workspace can have multiple flow files located anywhere in the workspace directory

Properties

Field	Type	Default	Required	Description
annotations	CommonAnnotations	map[]
description	string			A description of the executables defined within the flow file. This description will used as a shared description for all executables in the flow file.
descriptionFile	string			A path to a markdown file that contains the description of the executables defined within the flow file.
executables	array (Executable)	[]
imports	Imports	[]
namespace	string			The namespace to be given to all executables in the flow file. If not set, the executables in the file will be grouped into the root (*) namespace. Namespaces can be reused across multiple flow files. Namespaces are used to reference executables in the CLI using the format workspace:namespace/name.
tags	array (string)	[]		Tags to be applied to all executables defined within the flow file.
visibility	CommonVisibility

Definitions

CommonAliases

Alternate names that can be used to reference the executable in the CLI. Type: array (string)

CommonAnnotations

A map of arbitrary string key/value metadata attached to the object. Annotations are intended for use by external tools and integrations to store system metadata. Unlike tags, annotations are not used for filtering or display in the Flow UI - treat them as opaque state. Keys should be namespaced (e.g. my-tool.example.com/state) to avoid collisions between tools.

Type: map (string -> string)

CommonTags

A list of tags. Tags can be used with list commands to filter returned data.

Type: array (string)

CommonVisibility

The visibility of the executables to Flow. If not set, the visibility will default to public.

public executables can be executed and listed from anywhere. private executables can be executed and listed only within their own workspace. internal executables can be executed within their own workspace but are not listed. hidden executables cannot be executed or listed.

Type: string · Default: publicValid values: public, private, internal, hidden

ExecContainerVolume

Executable

The executable schema defines the structure of an executable in the Flow CLI. Executables are the building blocks of workflows and are used to define the actions that can be performed in a workspace.

Type: object

Field	Type	Default	Required	Description
aliases	CommonAliases	[]
annotations	CommonAnnotations	map[]
description	string			A description of the executable. This description is rendered as markdown in the interactive UI.
exec	ExecutableExecExecutableType
launch	ExecutableLaunchExecutableType
name	string			An optional name for the executable. Name is used to reference the executable in the CLI using the format workspace/namespace:name. [Verb group + Name] must be unique within the namespace of the workspace.
parallel	ExecutableParallelExecutableType
render	ExecutableRenderExecutableType
request	ExecutableRequestExecutableType
serial	ExecutableSerialExecutableType
tags	CommonTags	[]
timeout	string			The maximum amount of time the executable is allowed to run before being terminated. The timeout is specified in Go duration format (e.g. 30s, 5m, 1h).
verb	ExecutableVerb	exec	Yes
verbAliases	array (Verb)	[]		A list of aliases for the verb. This allows the executable to be referenced with multiple verbs.
visibility	CommonVisibility

ExecutableArgument

Type: object

Field	Type	Default	Required	Description
default	string			The default value to use if the argument is not provided. If the argument is required and no default is provided, the executable will fail.
envKey	string			The name of the environment variable that will be assigned the value.
flag	string			The flag to use when setting the argument from the command line. Either flag or pos must be set, but not both.
outputFile	string			A path where the argument value will be temporarily written to disk. The file will be created before execution and cleaned up afterwards.
pos	integer			The position of the argument in the command line ArgumentList. Values start at 1. Either flag or pos must be set, but not both.
required	boolean	false		If the argument is required, the executable will fail if the argument is not provided. If the argument is not required, the default value will be used if the argument is not provided.
type	string	string		The type of the argument. This is used to determine how to parse the value of the argument.

ExecutableArgumentList

Type: array (ExecutableArgument)

ExecutableDirectory

The directory to execute the command in. If unset, the directory of the flow file will be used. If set to f:tmp, a temporary directory will be created for the process. If prefixed with ./, the path will be relative to the current working directory. If prefixed with //, the path will be relative to the workspace root. Environment variables in the path will be expended at runtime.

Type: string

ExecutableExecContainer

Run the command or file inside a container instead of on the host. Requires docker or podman on the PATH.

Type: object

Field	Type	Default	Required	Description
entrypoint	string			The container entrypoint. Defaults to sh so that cmd behaves as a shell command regardless of the image's own ENTRYPOINT. Set to an empty string to use the image's ENTRYPOINT instead.
image	string		Yes	The container image to run in (e.g. golang:1.21-alpine).
inheritEnv	boolean			Pass the flow-resolved environment (parameters, arguments, and FLOW_* variables) into the container. Defaults to true. The host process environment is never forwarded regardless of this setting.
mountWorkspace	string	/workspace		The path inside the container where the workspace root is mounted.
network	string			The container network to attach to (e.g. host, none, or a named network). If unset, the runtime default is used.
runtime	string	auto		The container runtime to use. auto prefers docker and falls back to podman if docker is not on the PATH.
user	string			The user to run as inside the container, in uid, uid:gid, or name form. On Linux, defaults to the current host user so that files written to mounted volumes are not owned by root. Set to root to opt out.
volumes	array (ExecContainerVolume)	[]		Additional bind mounts to add to the container.
workdir	string			The working directory inside the container. If unset, the executable's resolved dir is translated to its path inside the workspace mount.

ExecutableExecExecutableType

Standard executable type. Runs a command/file in a subprocess. Type: object

Field	Type	Default	Required	Description
args	ExecutableArgumentList
cmd	string			The command to execute. Only one of cmd or file must be set.
container	ExecutableExecContainer
dir	ExecutableDirectory
file	string			The file to execute (.sh, .bat, .cmd, .ps1, .py). Only one of cmd or file must be set.
interpreter	ExecutableExecInterpreter			The interpreter used to run cmd. Defaults to sh, flow's built-in POSIX shell interpreter; python runs cmd as a Python script. When set, this also overrides the interpreter inferred from a file extension. When unset, file is run by the interpreter matching its extension, so file: script.py runs under Python without setting this.
logMode	string	logfmt		The log mode to use when running the executable. This can either be hidden, json, logfmt or text
params	ExecutableParameterList

ExecutableExecInterpreter

The interpreter used to run a command. sh uses flow's built-in POSIX shell interpreter; python runs the command as a Python script.

Type: stringValid values: sh, python

ExecutableLaunchExecutableType

Launches an application or opens a URI. Type: object

Field	Type	Default	Required	Description
app	string			The application to launch the URI with.
args	ExecutableArgumentList
params	ExecutableParameterList
uri	string		Yes	The URI to launch. This can be a file path or a web URL.

ExecutableParallelExecutableType

Type: object

Field	Type	Default	Required	Description
args	ExecutableArgumentList
dir	ExecutableDirectory
execs	ExecutableParallelRefConfigList		Yes	A list of executables to run in parallel. Each executable can be a command or a reference to another executable.
failFast	boolean			End the parallel execution as soon as an exec exits with a non-zero status. This is the default behavior. When set to false, all execs will be run regardless of the exit status of parallel execs.
maxThreads	integer	5		The maximum number of threads to use when executing the parallel executables.
params	ExecutableParameterList

ExecutableParallelRefConfig

Configuration for a parallel executable. Type: object

Field	Type	Default	Required	Description
args	array (string)	[]		Arguments to pass to the executable.
cmd	string			The command to execute. One of cmd or ref must be set.
if	string			An expression that determines whether the executable should run, using the Expr language syntax. The expression is evaluated at runtime and must resolve to a boolean value. The expression has access to OS/architecture information (os, arch), environment variables (env), stored data (store), and context information (ctx) like workspace and paths. For example, os == "darwin" will only run on macOS, len(store["feature"]) > 0 will run if a value exists in the store, and env["CI"] == "true" will run in CI environments. See the Expr documentation for more information.
interpreter	ExecutableExecInterpreter			The interpreter used to run cmd for this step. Defaults to sh. Only applies to cmd; a ref uses the referenced executable's own interpreter.
name	string			A human-readable label for this step, used for display purposes.
ref	ExecutableRef			A reference to another executable to run in serial. One of cmd or ref must be set.
retries	integer	0		The number of times to retry the executable if it fails.

ExecutableParallelRefConfigList

A list of executables to run in parallel. The executables can be defined by it's exec cmd or ref.

Type: array (ExecutableParallelRefConfig)

ExecutableParameter

A parameter is a value that can be passed to an executable and all of its sub-executables. Only one of text, secretRef, prompt, or file must be set. Specifying more than one will result in an error.

Type: object

Field	Type	Default	Required	Description
envFile	string			A path to a file containing environment variables to be passed to the executable. The file should contain one variable per line in the format KEY=VALUE.
envKey	string			The name of the environment variable that will be assigned the value. When specified with envFile, only the environment variable with this name will be set.
outputFile	string			A path where the parameter value will be temporarily written to disk. The file will be created before execution and cleaned up afterwards.
prompt	string			A prompt to be displayed to the user when collecting an input value.
secretRef	string			A reference to a secret to be passed to the executable.
text	string			A static value to be passed to the executable.

ExecutableParameterList

Type: array (ExecutableParameter)

ExecutableRef

A reference to an executable. The format is <verb> <workspace>/<namespace>:<executable name>. For example, exec ws/ns:my-workflow.

• If the workspace is not specified, the current workspace will be used.
• If the namespace is not specified, the current namespace will be used.
• Excluding the name will reference the executable with a matching verb but an unspecified name and namespace (e.g. exec ws or simply exec).

Type: string

ExecutableRenderExecutableType

Renders a markdown template file with data. Type: object

Field	Type	Default	Required	Description
args	ExecutableArgumentList
dir	ExecutableDirectory
params	ExecutableParameterList
templateDataFile	string			The path to the JSON or YAML file containing the template data.
templateFile	string			The path to the markdown template file to render.

ExecutableRequestExecutableType

Makes an HTTP request. Type: object

Field	Type	Default	Required	Description
args	ExecutableArgumentList
body	string			The body of the request.
headers	map (string -> string)	map[]		A map of headers to include in the request.
logResponse	boolean	false		If set to true, the response will be logged as program output.
method	string	GET		The HTTP method to use when making the request.
params	ExecutableParameterList
responseFile	ExecutableRequestResponseFile
timeout	string	30m0s		The timeout for the request in Go duration format (e.g. 30s, 5m, 1h).
transformResponse	string			Expr expression used to transform the response before saving it to a file or outputting it. The following variables are available in the expression: - status: The response status string. - code: The response status code. - body: The response body. - headers: The response headers. For example, to capitalize a JSON body field's value, you can use upper(fromJSON(body)["field"]).
url	string		Yes	The URL to make the request to.
validStatusCodes	array (integer)	[]		A list of valid status codes. If the response status code is not in this list, the executable will fail. If not set, the response status code will not be checked.

ExecutableRequestResponseFile

Configuration for saving the response of a request to a file. Type: object

Field	Type	Default	Required	Description
dir	ExecutableDirectory
filename	string		Yes	The name of the file to save the response to.
saveAs	string	raw		The format to save the response as.

ExecutableSerialExecutableType

Executes a list of executables in serial. Type: object

Field	Type	Default	Required	Description
args	ExecutableArgumentList
dir	ExecutableDirectory
execs	ExecutableSerialRefConfigList		Yes	A list of executables to run in serial. Each executable can be a command or a reference to another executable.
failFast	boolean			End the serial execution as soon as an exec exits with a non-zero status. This is the default behavior. When set to false, all execs will be run regardless of the exit status of the previous exec.
params	ExecutableParameterList

ExecutableSerialRefConfig

Configuration for a serial executable. Type: object

Field	Type	Default	Required	Description
args	array (string)	[]		Arguments to pass to the executable.
cmd	string			The command to execute. One of cmd or ref must be set.
if	string			An expression that determines whether the executable should run, using the Expr language syntax. The expression is evaluated at runtime and must resolve to a boolean value. The expression has access to OS/architecture information (os, arch), environment variables (env), stored data (store), and context information (ctx) like workspace and paths. For example, os == "darwin" will only run on macOS, len(store["feature"]) > 0 will run if a value exists in the store, and env["CI"] == "true" will run in CI environments. See the Expr documentation for more information.
interpreter	ExecutableExecInterpreter			The interpreter used to run cmd for this step. Defaults to sh. Only applies to cmd; a ref uses the referenced executable's own interpreter.
name	string			A human-readable label for this step, used for display purposes.
ref	ExecutableRef			A reference to another executable to run in serial. One of cmd or ref must be set.
retries	integer	0		The number of times to retry the executable if it fails.
reviewRequired	boolean	false		If set to true, the user will be prompted to review the output of the executable before continuing.

ExecutableSerialRefConfigList

A list of executables to run in serial. The executables can be defined by it's exec cmd or ref.

Type: array (ExecutableSerialRefConfig)

ExecutableVerb

Keywords that describe the action an executable performs. Executables are configured with a single verb, but core verbs have aliases that can be used interchangeably when referencing executables. This allows users to use the verb that best describes the action they are performing.

Default Verb Aliases

• Execution Group: exec, run, execute
• Retrieval Group: get, fetch, retrieve
• Display Group: show, view, list
• Configuration Group: configure, setup
• Update Group: update, upgrade

Usage Notes

1. [Verb + Name] must be unique within the namespace of the workspace.
2. When referencing an executable, users can use any verb from the default or configured alias group.
3. All other verbs are standalone and self-descriptive.

Examples

• An executable configured with the exec verb can also be referenced using "run" or "execute".
• An executable configured with get can also be called with "list", "show", or "view".
• Operations like backup, migrate, flush are standalone verbs without aliases.
• Use domain-specific verbs like deploy, scale, tunnel for clear operational intent.

By providing minimal aliasing with comprehensive verb coverage, flow enables natural language operations while maintaining simplicity and flexibility for diverse development and operations workflows.

Type: string · Default: execValid values: abort, activate, add, analyze, apply, archive, audit, backup, benchmark, build, bundle, check, clean, clear, commit, compile, compress, configure, connect, copy, create, deactivate, debug, decompress, decrypt, delete, deploy, destroy, disable, disconnect, edit, enable, encrypt, erase, exec, execute, export, expose, fetch, fix, flush, format, generate, get, import, index, init, inspect, install, join, kill, launch, lint, list, load, lock, login, logout, manage, merge, migrate, modify, monitor, mount, new, notify, open, package, partition, patch, pause, ping, preload, prefetch, profile, provision, publish, purge, push, queue, reboot, recover, refresh, release, reload, remove, request, reset, restart, restore, retrieve, rollback, run, save, scale, scan, schedule, seed, send, serve, set, setup, show, snapshot, start, stash, stop, tag, teardown, terminate, test, tidy, trace, transform, trigger, tunnel, undeploy, uninstall, unmount, unset, update, upgrade, validate, verify, view, watch

Imports

A list of script files (.sh, .bat, .cmd, .ps1) to convert into generated executables in the file's executable group. Type: array (string)

Ref

Verb