atmos.composition

The atmos.composition function runs atmos composition through the current Atmos executable. Use it to list declared compositions, check which services a stack fulfills, and start, stop, or inspect the members of a composition from automation.

Usage

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

Subcommands

Pass the subcommand and any positional arguments as strings before the keyword arguments. The call atmos.composition("validate", "storefront", flags = {"stack": "dev"}) runs atmos composition validate storefront --stack=dev.

Subcommand	Purpose
list	List declared compositions and stack fulfillment.
validate	Report a composition's fulfilled and not-provided services for a stack.
up	Bring composition members in a stack up.
start	Start composition members in a stack.
stop	Stop composition members in a stack.
restart	Restart composition members in a stack.
down	Bring composition members in a stack down.
rm	Remove composition members in a stack.
ps	List composition members in a stack.
logs	Show logs from composition members in a stack.

See the atmos composition command reference for the complete list of subcommands and flags.

Arguments

*positionals

(Optional) Strings placed on the command line right after composition, in order: the subcommand and its positional arguments, such as the composition name. Every value must be a string.

flags

(Optional) A dictionary of command-line options; see flag translation. The stack key becomes --stack and applies to every subcommand that operates on a stack, format and sort apply to list, and follow and tail apply to logs.

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

Check that a stack fulfills a composition

check = atmos.composition("validate", "storefront", flags = {"stack": "dev"}, output = "capture", check = False)
if check.exit_code != 0:
    fail("The dev stack does not fulfill the storefront composition:\n" + check.stderr)
ui.success("The dev stack fulfills the storefront composition.")

Read the declared compositions as data

listing = atmos.composition("list", flags = {"format": "json"}, output = "capture")
for composition in json.decode(listing.stdout):
    print(composition["Composition"], "->", composition["Services"])

The list subcommand prints one object per composition, with the keys Composition, Description, Services, and Stacks.

Start a composition

atmos.composition("up", "storefront", flags = {"stack": "local"})

Related

• atmos.run runs any Atmos command from an argument list.
• atmos composition documents every subcommand and flag.
• Atmos Automation Language and the script step