{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://flowexec.io/schemas/flowfile_schema.json",
  "title": "FlowFile",
  "description": "Configuration for a group of Flow CLI executables. The file must have the extension `.flow`, `.flow.yaml`, or `.flow.yml`\nin order to be discovered by the CLI. It's configuration is used to define a group of executables with shared metadata\n(namespace, tags, etc). A workspace can have multiple flow files located anywhere in the workspace directory\n",
  "type": "object",
  "definitions": {
    "CommonAliases": {
      "description": "Alternate names that can be used to reference the executable in the CLI.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "CommonAnnotations": {
      "description": "A map of arbitrary string key/value metadata attached to the object.\nAnnotations are intended for use by external tools and integrations to\nstore system metadata. Unlike tags, annotations are not used for\nfiltering or display in the Flow UI - treat them as opaque state.\nKeys should be namespaced (e.g. `my-tool.example.com/state`) to avoid\ncollisions between tools.\n",
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "CommonTags": {
      "description": "A list of tags.\nTags can be used with list commands to filter returned data.\n",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "CommonVisibility": {
      "description": "The visibility of the executables to Flow.\nIf not set, the visibility will default to `public`.\n\n`public` executables can be executed and listed from anywhere.\n`private` executables can be executed and listed only within their own workspace.\n`internal` executables can be executed within their own workspace but are not listed.\n`hidden` executables cannot be executed or listed.\n",
      "type": "string",
      "default": "public",
      "enum": [
        "public",
        "private",
        "internal",
        "hidden"
      ]
    },
    "Executable": {
      "title": "Executable",
      "description": "The executable schema defines the structure of an executable in the Flow CLI.\nExecutables are the building blocks of workflows and are used to define the actions that can be performed in a workspace.\n",
      "type": "object",
      "required": [
        "verb"
      ],
      "properties": {
        "aliases": {
          "$ref": "#/definitions/CommonAliases",
          "default": []
        },
        "annotations": {
          "$ref": "#/definitions/CommonAnnotations",
          "default": {}
        },
        "description": {
          "description": "A description of the executable.\nThis description is rendered as markdown in the interactive UI.\n",
          "type": "string",
          "default": ""
        },
        "exec": {
          "$ref": "#/definitions/ExecutableExecExecutableType"
        },
        "launch": {
          "$ref": "#/definitions/ExecutableLaunchExecutableType"
        },
        "name": {
          "description": "An optional name for the executable.\n\nName is used to reference the executable in the CLI using the format `workspace/namespace:name`.\n[Verb group + Name] must be unique within the namespace of the workspace.\n",
          "type": "string",
          "default": ""
        },
        "parallel": {
          "$ref": "#/definitions/ExecutableParallelExecutableType"
        },
        "render": {
          "$ref": "#/definitions/ExecutableRenderExecutableType"
        },
        "request": {
          "$ref": "#/definitions/ExecutableRequestExecutableType"
        },
        "serial": {
          "$ref": "#/definitions/ExecutableSerialExecutableType"
        },
        "tags": {
          "$ref": "#/definitions/CommonTags",
          "default": []
        },
        "timeout": {
          "description": "The maximum amount of time the executable is allowed to run before being terminated.\nThe timeout is specified in Go duration format (e.g. 30s, 5m, 1h).\n",
          "type": "string"
        },
        "verb": {
          "$ref": "#/definitions/ExecutableVerb",
          "default": "exec"
        },
        "verbAliases": {
          "description": "A list of aliases for the verb. This allows the executable to be referenced with multiple verbs.",
          "type": "array",
          "default": [],
          "items": {
            "$ref": "#/definitions/Verb"
          }
        },
        "visibility": {
          "$ref": "#/definitions/CommonVisibility"
        }
      }
    },
    "ExecutableArgument": {
      "type": "object",
      "properties": {
        "default": {
          "description": "The default value to use if the argument is not provided.\nIf the argument is required and no default is provided, the executable will fail.\n",
          "type": "string",
          "default": ""
        },
        "envKey": {
          "description": "The name of the environment variable that will be assigned the value.",
          "type": "string",
          "default": ""
        },
        "flag": {
          "description": "The flag to use when setting the argument from the command line.\nEither `flag` or `pos` must be set, but not both.\n",
          "type": "string",
          "default": ""
        },
        "outputFile": {
          "description": "A path where the argument value will be temporarily written to disk.\nThe file will be created before execution and cleaned up afterwards.\n",
          "type": "string",
          "default": ""
        },
        "pos": {
          "description": "The position of the argument in the command line ArgumentList. Values start at 1.\nEither `flag` or `pos` must be set, but not both.\n",
          "type": "integer"
        },
        "required": {
          "description": "If the argument is required, the executable will fail if the argument is not provided.\nIf the argument is not required, the default value will be used if the argument is not provided.\n",
          "type": "boolean",
          "default": false
        },
        "type": {
          "description": "The type of the argument. This is used to determine how to parse the value of the argument.",
          "type": "string",
          "default": "string",
          "enum": [
            "string",
            "int",
            "float",
            "bool"
          ]
        }
      }
    },
    "ExecutableArgumentList": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/ExecutableArgument"
      }
    },
    "ExecutableDirectory": {
      "description": "The directory to execute the command in.\nIf unset, the directory of the flow file will be used.\nIf set to `f:tmp`, a temporary directory will be created for the process.\nIf prefixed with `./`, the path will be relative to the current working directory.\nIf prefixed with `//`, the path will be relative to the workspace root.\nEnvironment variables in the path will be expended at runtime.\n",
      "type": "string",
      "default": ""
    },
    "ExecutableExecExecutableType": {
      "description": "Standard executable type. Runs a command/file in a subprocess.",
      "type": "object",
      "properties": {
        "args": {
          "$ref": "#/definitions/ExecutableArgumentList"
        },
        "cmd": {
          "description": "The command to execute.\nOnly one of `cmd` or `file` must be set.\n",
          "type": "string",
          "default": ""
        },
        "dir": {
          "$ref": "#/definitions/ExecutableDirectory",
          "default": ""
        },
        "file": {
          "description": "The file to execute (`.sh`, `.bat`, `.cmd`, `.ps1`).\nOnly one of `cmd` or `file` must be set.\n",
          "type": "string",
          "default": ""
        },
        "logMode": {
          "description": "The log mode to use when running the executable.\nThis can either be `hidden`, `json`, `logfmt` or `text`\n",
          "type": "string",
          "default": "logfmt"
        },
        "params": {
          "$ref": "#/definitions/ExecutableParameterList"
        }
      }
    },
    "ExecutableLaunchExecutableType": {
      "description": "Launches an application or opens a URI.",
      "type": "object",
      "required": [
        "uri"
      ],
      "properties": {
        "app": {
          "description": "The application to launch the URI with.",
          "type": "string",
          "default": ""
        },
        "args": {
          "$ref": "#/definitions/ExecutableArgumentList"
        },
        "params": {
          "$ref": "#/definitions/ExecutableParameterList"
        },
        "uri": {
          "description": "The URI to launch. This can be a file path or a web URL.",
          "type": "string",
          "default": ""
        }
      }
    },
    "ExecutableParallelExecutableType": {
      "type": "object",
      "required": [
        "execs"
      ],
      "properties": {
        "args": {
          "$ref": "#/definitions/ExecutableArgumentList"
        },
        "dir": {
          "$ref": "#/definitions/ExecutableDirectory",
          "default": ""
        },
        "execs": {
          "$ref": "#/definitions/ExecutableParallelRefConfigList",
          "description": "A list of executables to run in parallel.\nEach executable can be a command or a reference to another executable.\n"
        },
        "failFast": {
          "description": "End the parallel execution as soon as an exec exits with a non-zero status. This is the default behavior.\nWhen set to false, all execs will be run regardless of the exit status of parallel execs.\n",
          "type": "boolean"
        },
        "maxThreads": {
          "description": "The maximum number of threads to use when executing the parallel executables.",
          "type": "integer",
          "default": 5
        },
        "params": {
          "$ref": "#/definitions/ExecutableParameterList"
        }
      }
    },
    "ExecutableParallelRefConfig": {
      "description": "Configuration for a parallel executable.",
      "type": "object",
      "properties": {
        "args": {
          "description": "Arguments to pass to the executable.",
          "type": "array",
          "default": [],
          "items": {
            "type": "string"
          }
        },
        "cmd": {
          "description": "The command to execute.\nOne of `cmd` or `ref` must be set.\n",
          "type": "string",
          "default": ""
        },
        "if": {
          "description": "An expression that determines whether the executable should run, using the Expr language syntax.\nThe expression is evaluated at runtime and must resolve to a boolean value.\n\nThe expression has access to OS/architecture information (os, arch), environment variables (env), stored data\n(store), and context information (ctx) like workspace and paths.\n\nFor example, `os == \"darwin\"` will only run on macOS, `len(store[\"feature\"]) \u003e 0` will run if a value exists\nin the store, and `env[\"CI\"] == \"true\"` will run in CI environments.\nSee the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information.\n",
          "type": "string",
          "default": ""
        },
        "name": {
          "description": "A human-readable label for this step, used for display purposes.",
          "type": "string",
          "default": ""
        },
        "ref": {
          "$ref": "#/definitions/ExecutableRef",
          "description": "A reference to another executable to run in serial.\nOne of `cmd` or `ref` must be set.\n",
          "default": ""
        },
        "retries": {
          "description": "The number of times to retry the executable if it fails.",
          "type": "integer",
          "default": 0
        }
      }
    },
    "ExecutableParallelRefConfigList": {
      "description": "A list of executables to run in parallel. The executables can be defined by it's exec `cmd` or `ref`.\n",
      "type": "array",
      "items": {
        "$ref": "#/definitions/ExecutableParallelRefConfig"
      }
    },
    "ExecutableParameter": {
      "description": "A parameter is a value that can be passed to an executable and all of its sub-executables.\nOnly one of `text`, `secretRef`, `prompt`, or `file` must be set. Specifying more than one will result in an error.\n",
      "type": "object",
      "properties": {
        "envFile": {
          "description": "A path to a file containing environment variables to be passed to the executable.\nThe file should contain one variable per line in the format `KEY=VALUE`.\n",
          "type": "string",
          "default": ""
        },
        "envKey": {
          "description": "The name of the environment variable that will be assigned the value.\n\nWhen specified with `envFile`, only the environment variable with this name will be set.\n",
          "type": "string",
          "default": ""
        },
        "outputFile": {
          "description": "A path where the parameter value will be temporarily written to disk.\nThe file will be created before execution and cleaned up afterwards.\n",
          "type": "string",
          "default": ""
        },
        "prompt": {
          "description": "A prompt to be displayed to the user when collecting an input value.",
          "type": "string",
          "default": ""
        },
        "secretRef": {
          "description": "A reference to a secret to be passed to the executable.",
          "type": "string",
          "default": ""
        },
        "text": {
          "description": "A static value to be passed to the executable.",
          "type": "string",
          "default": ""
        }
      }
    },
    "ExecutableParameterList": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/ExecutableParameter"
      }
    },
    "ExecutableRef": {
      "description": "A reference to an executable.\nThe format is `\u003cverb\u003e \u003cworkspace\u003e/\u003cnamespace\u003e:\u003cexecutable name\u003e`.\nFor example, `exec ws/ns:my-workflow`.\n\n- If the workspace is not specified, the current workspace will be used.\n- If the namespace is not specified, the current namespace will be used.\n- Excluding the name will reference the executable with a matching verb but an unspecified name and namespace (e.g. `exec ws` or simply `exec`).\n",
      "type": "string"
    },
    "ExecutableRenderExecutableType": {
      "description": "Renders a markdown template file with data.",
      "type": "object",
      "required": [
        "templateFile"
      ],
      "properties": {
        "args": {
          "$ref": "#/definitions/ExecutableArgumentList"
        },
        "dir": {
          "$ref": "#/definitions/ExecutableDirectory",
          "default": ""
        },
        "params": {
          "$ref": "#/definitions/ExecutableParameterList"
        },
        "templateDataFile": {
          "description": "The path to the JSON or YAML file containing the template data.",
          "type": "string",
          "default": ""
        },
        "templateFile": {
          "description": "The path to the markdown template file to render.",
          "type": "string",
          "default": ""
        }
      }
    },
    "ExecutableRequestExecutableType": {
      "description": "Makes an HTTP request.",
      "type": "object",
      "required": [
        "url"
      ],
      "properties": {
        "args": {
          "$ref": "#/definitions/ExecutableArgumentList"
        },
        "body": {
          "description": "The body of the request.",
          "type": "string",
          "default": ""
        },
        "headers": {
          "description": "A map of headers to include in the request.",
          "type": "object",
          "default": {},
          "additionalProperties": {
            "type": "string"
          }
        },
        "logResponse": {
          "description": "If set to true, the response will be logged as program output.",
          "type": "boolean",
          "default": false
        },
        "method": {
          "description": "The HTTP method to use when making the request.",
          "type": "string",
          "default": "GET",
          "enum": [
            "GET",
            "POST",
            "PUT",
            "PATCH",
            "DELETE"
          ]
        },
        "params": {
          "$ref": "#/definitions/ExecutableParameterList"
        },
        "responseFile": {
          "$ref": "#/definitions/ExecutableRequestResponseFile"
        },
        "timeout": {
          "description": "The timeout for the request in Go duration format (e.g. 30s, 5m, 1h).",
          "type": "string",
          "default": "30m0s"
        },
        "transformResponse": {
          "description": "[Expr](https://expr-lang.org/docs/language-definition) expression used to transform the response before\nsaving it to a file or outputting it.\n\nThe following variables are available in the expression:\n  - `status`: The response status string.\n  - `code`: The response status code.\n  - `body`: The response body.\n  - `headers`: The response headers.\n\nFor example, to capitalize a JSON body field's value, you can use `upper(fromJSON(body)[\"field\"])`.\n",
          "type": "string",
          "default": ""
        },
        "url": {
          "description": "The URL to make the request to.",
          "type": "string",
          "default": ""
        },
        "validStatusCodes": {
          "description": "A list of valid status codes. If the response status code is not in this list, the executable will fail.\nIf not set, the response status code will not be checked.\n",
          "type": "array",
          "default": [],
          "items": {
            "type": "integer"
          }
        }
      }
    },
    "ExecutableRequestResponseFile": {
      "description": "Configuration for saving the response of a request to a file.",
      "type": "object",
      "required": [
        "filename"
      ],
      "properties": {
        "dir": {
          "$ref": "#/definitions/ExecutableDirectory",
          "default": ""
        },
        "filename": {
          "description": "The name of the file to save the response to.",
          "type": "string",
          "default": ""
        },
        "saveAs": {
          "description": "The format to save the response as.",
          "type": "string",
          "default": "raw",
          "enum": [
            "raw",
            "json",
            "indented-json",
            "yaml",
            "yml"
          ]
        }
      }
    },
    "ExecutableSerialExecutableType": {
      "description": "Executes a list of executables in serial.",
      "type": "object",
      "required": [
        "execs"
      ],
      "properties": {
        "args": {
          "$ref": "#/definitions/ExecutableArgumentList"
        },
        "dir": {
          "$ref": "#/definitions/ExecutableDirectory",
          "default": ""
        },
        "execs": {
          "$ref": "#/definitions/ExecutableSerialRefConfigList",
          "description": "A list of executables to run in serial.\nEach executable can be a command or a reference to another executable.\n"
        },
        "failFast": {
          "description": "End the serial execution as soon as an exec exits with a non-zero status. This is the default behavior.\nWhen set to false, all execs will be run regardless of the exit status of the previous exec.\n",
          "type": "boolean"
        },
        "params": {
          "$ref": "#/definitions/ExecutableParameterList"
        }
      }
    },
    "ExecutableSerialRefConfig": {
      "description": "Configuration for a serial executable.",
      "type": "object",
      "properties": {
        "args": {
          "description": "Arguments to pass to the executable.",
          "type": "array",
          "default": [],
          "items": {
            "type": "string"
          }
        },
        "cmd": {
          "description": "The command to execute.\nOne of `cmd` or `ref` must be set.\n",
          "type": "string",
          "default": ""
        },
        "if": {
          "description": "An expression that determines whether the executable should run, using the Expr language syntax.\nThe expression is evaluated at runtime and must resolve to a boolean value.\n\nThe expression has access to OS/architecture information (os, arch), environment variables (env), stored data\n(store), and context information (ctx) like workspace and paths.\n\nFor example, `os == \"darwin\"` will only run on macOS, `len(store[\"feature\"]) \u003e 0` will run if a value exists\nin the store, and `env[\"CI\"] == \"true\"` will run in CI environments.\nSee the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information.\n",
          "type": "string",
          "default": ""
        },
        "name": {
          "description": "A human-readable label for this step, used for display purposes.",
          "type": "string",
          "default": ""
        },
        "ref": {
          "$ref": "#/definitions/ExecutableRef",
          "description": "A reference to another executable to run in serial.\nOne of `cmd` or `ref` must be set.\n",
          "default": ""
        },
        "retries": {
          "description": "The number of times to retry the executable if it fails.",
          "type": "integer",
          "default": 0
        },
        "reviewRequired": {
          "description": "If set to true, the user will be prompted to review the output of the executable before continuing.",
          "type": "boolean",
          "default": false
        }
      }
    },
    "ExecutableSerialRefConfigList": {
      "description": "A list of executables to run in serial. The executables can be defined by it's exec `cmd` or `ref`.\n",
      "type": "array",
      "items": {
        "$ref": "#/definitions/ExecutableSerialRefConfig"
      }
    },
    "ExecutableVerb": {
      "description": "Keywords that describe the action an executable performs. Executables are configured with a single verb,\nbut core verbs have aliases that can be used interchangeably when referencing executables. This allows users \nto use the verb that best describes the action they are performing.\n\n### Default Verb Aliases\n\n- **Execution Group**: `exec`, `run`, `execute`\n- **Retrieval Group**: `get`, `fetch`, `retrieve`\n- **Display Group**: `show`, `view`, `list`\n- **Configuration Group**: `configure`, `setup`\n- **Update Group**: `update`, `upgrade`\n\n### Usage Notes\n\n1. [Verb + Name] must be unique within the namespace of the workspace.\n2. When referencing an executable, users can use any verb from the default or configured alias group.\n3. All other verbs are standalone and self-descriptive.\n\n### Examples\n\n- An executable configured with the `exec` verb can also be referenced using \"run\" or \"execute\".\n- An executable configured with `get` can also be called with \"list\", \"show\", or \"view\".\n- Operations like `backup`, `migrate`, `flush` are standalone verbs without aliases.\n- Use domain-specific verbs like `deploy`, `scale`, `tunnel` for clear operational intent.\n\nBy providing minimal aliasing with comprehensive verb coverage, flow enables natural language operations\nwhile maintaining simplicity and flexibility for diverse development and operations workflows.\n",
      "type": "string",
      "default": "exec",
      "enum": [
        "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": {
      "description": "A list of script files (`.sh`, `.bat`, `.cmd`, `.ps1`) to convert into generated executables in the file's executable group.",
      "type": "array",
      "default": [],
      "items": {
        "type": "string"
      }
    },
    "Ref": {},
    "Verb": {}
  },
  "properties": {
    "annotations": {
      "$ref": "#/definitions/CommonAnnotations",
      "default": {}
    },
    "description": {
      "description": "A description of the executables defined within the flow file. This description will used as a shared description\nfor all executables in the flow file.\n",
      "type": "string",
      "default": ""
    },
    "descriptionFile": {
      "description": "A path to a markdown file that contains the description of the executables defined within the flow file.",
      "type": "string",
      "default": ""
    },
    "executables": {
      "type": "array",
      "default": [],
      "items": {
        "$ref": "#/definitions/Executable"
      }
    },
    "imports": {
      "$ref": "#/definitions/Imports",
      "default": []
    },
    "namespace": {
      "description": "The namespace to be given to all executables in the flow file.\nIf not set, the executables in the file will be grouped into the root (*) namespace.\nNamespaces can be reused across multiple flow files.\n\nNamespaces are used to reference executables in the CLI using the format `workspace:namespace/name`.\n",
      "type": "string",
      "default": ""
    },
    "tags": {
      "description": "Tags to be applied to all executables defined within the flow file.",
      "type": "array",
      "default": [],
      "items": {
        "type": "string"
      }
    },
    "visibility": {
      "$ref": "#/definitions/CommonVisibility"
    }
  }
}