Skip to main content

atmos.scaffold

The atmos.scaffold function runs atmos scaffold through the current Atmos executable. Use it to list templates, validate scaffold manifests, and generate projects or components from templates in automation.

Usage​

atmos.scaffold(
    *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.scaffold("list") runs atmos scaffold list.

SubcommandPurpose
generateGenerate code from a scaffold template.
listList available scaffold templates.
validateValidate scaffold template configuration.

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

Arguments​

*positionals

(Optional) Strings placed on the command line right after scaffold, in order: the subcommand and its positional arguments. For generate, these are the template and the target directory. Every value must be a string.

flags

(Optional) A dictionary of command-line options; see flag translation. A bare key such as "dry-run" becomes --dry-run, and registered shorthands such as "f" for --force resolve to their long form. For generate, useful keys include "set" (a list of key=value strings), "defaults", "force", "dry-run", and "ref".

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​

Generate a project without prompting​

atmos.scaffold(
    "generate",
    "aws/app",
    "./my-app",
    flags = {"defaults": True, "set": ["project_name=my-app"]},
)

This runs atmos scaffold generate aws/app ./my-app --defaults --set=project_name=my-app. The defaults flag makes the command use field defaults and the set values instead of prompting for input.

Preview the changes first​

preview = atmos.scaffold("generate", "./templates/service", "./services/api", flags = {"dry-run": True}, output = "capture")
print(preview.stderr)

Validate scaffold manifests before generating​

result = atmos.scaffold("validate", "./templates/service", output = "capture", check = False)
if result.exit_code != 0:
    fail("The scaffold manifest is not valid:\n" + result.stderr)
ui.success("The scaffold manifest is valid.")

Notes​

note

The atmos scaffold command is experimental, so its notice appears on standard error. The generate command prompts for field values when a terminal is available. In a script, pass defaults along with set values so the call does not wait for input.

Related​