Skip to main content

atmos.init

The atmos.init function runs atmos init through the current Atmos executable. Use it to scaffold a new Atmos project from a built-in or remote template as part of provisioning automation.

Usage​

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

Subcommands​

The init command has no subcommands. Its positional arguments are the template and the target directory, so atmos.init("basic", "./my-project") runs atmos init basic ./my-project. The built-in templates include basic, simple, atmos, aws/app, aws/landing-zone, gcp/landing-zone, and azure/landing-zone. A template can also be a Git repository address.

The flags this command accepts include:

FlagPurpose
--setSet a template value as key=value. Repeat the flag for several values.
--forceOverwrite existing files.
--interactiveTurn interactive template selection and prompts on or off.
--no-gitSkip creating a Git repository and the initial commit.
--refGit ref to use for a template repository source.
--updateUpdate an existing target directory with a 3-way merge instead of failing.

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

Arguments​

*positionals

(Optional) Strings placed on the command line right after init, in order: the template, then 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 "no-git" becomes --no-git, and registered shorthands such as "f" resolve to the long form --force. A list is the natural way to pass several set values.

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

(Optional) The same process options as atmos.run. The call runs from the directory Atmos was started in by default, so a relative target directory is created there.

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​

Scaffold a project without prompts​

atmos.init(
    "basic",
    "./my-project",
    flags = {
        "set": ["project_name=my-project"],
        "interactive": False,
        "no-git": True,
    },
)

This runs atmos init basic ./my-project --interactive=false --no-git --set=project_name=my-project.

Scaffold into a chosen directory​

atmos.init(
    "aws/app",
    "my-app",
    flags = {"set": ["project_name=my-app"], "interactive": False},
    working_directory = "/workspace/projects",
)

Handle an existing directory​

result = atmos.init("simple", "./my-project", flags = {"interactive": False}, output = "capture", check = False)
if result.exit_code != 0:
    ui.warning("Project was not created:\n" + result.stderr)
note

The command is experimental. Without a template and target directory it asks for them interactively, which needs a terminal. Pass both positionals and set interactive to False when the script runs unattended.

Related​