Skip to main content

atmos.workflow

The atmos.workflow function runs atmos workflow through the current Atmos executable. Use it to run a named workflow from a script, resume it from a step, or list the workflows defined in the project.

Usage​

atmos.workflow(
    *positionals,
    flags = {},
    args = [],
    working_directory = ...,
    env = ...,
    output = "stream",
    check = True,
)

Subcommands​

The first positional is the workflow name. The call atmos.workflow("deploy", flags = {"file": "deploy"}) runs atmos workflow deploy --file=deploy.

PositionalPurpose
NAMERun the workflow with this name. Without file, Atmos finds the workflow across all workflow files.
listList all Atmos workflows. This is an alias for atmos list workflows.

See the atmos workflow command reference for the complete list of flags.

Arguments​

*positionals

(Optional) Strings placed on the command line right after workflow, in order: the workflow name, or "list". Every value must be a string.

flags

(Optional) A dictionary of command-line options; see flag translation. A bare key such as "file" becomes --file, and registered shorthands such as "f" and "s" resolve to --file and --stack. Common keys for running a workflow are "file", "stack", "from-step", "dry-run", and "identity". The list form accepts "format", "columns", "sort", and "file".

args
(Optional) A list or tuple of strings appended after the flags.
working_directory, env, output, check

(Optional) See atmos.run for process options and defaults.

Options other than the positionals are keyword-only.

Returns​

A result with stdout, stderr, and exit_code. See atmos.run for output and error behavior.

Examples​

Run a workflow​

atmos.workflow("deploy", flags = {"file": "deploy", "stack": "dev"})

This runs atmos workflow deploy --file=deploy --stack=dev.

Preview a workflow without changes​

atmos.workflow("deploy", flags = {"file": "deploy", "dry-run": True})

Resume from a step​

atmos.workflow("deploy", flags = {"file": "deploy", "from-step": "plan"})

Choose a workflow from the list​

The list form with format set to json returns the workflows as data, so a script can decide what to run.

listing = atmos.workflow("list", flags = {"format": "json"}, output = "capture")
for workflow in json.decode(listing.stdout):
    ui.info(workflow["Workflow"] + " in " + workflow["File"] + ": " + workflow["Description"])

Handle a failed workflow​

result = atmos.workflow("deploy", flags = {"file": "deploy"}, output = "capture", check = False)
if result.exit_code != 0:
    ui.warning("The deploy workflow failed.")
    print(result.stderr)

Notes​

note

Always pass a workflow name. Without one, atmos workflow opens an interactive selector that needs a terminal, which a script cannot answer. When the same name exists in several workflow files, Atmos asks which one to run, so pass file to make the call unambiguous.

Related​