# atmos init

Initialize a project from a proven Atmos starting point. `atmos init` selects a project template,
collects its validated answers, generates the project, and records the source needed for later
updates.

## Usage

```shell
atmos init [template] [target] [flags]
```

```shell
# Choose a template and target interactively.
atmos init

# Initialize a minimal cloud-agnostic project.
atmos init basic ./my-project

# Initialize an AWS application or landing-zone foundation.
atmos init aws/app ./my-app
atmos init aws/landing-zone ./my-platform

# Provide values for automated project creation.
atmos init basic ./my-project --set project_name=my-project --interactive=false
```

## Templates

The built-in catalog includes `basic`, `simple`, `atmos`, `aws/app`,
`aws/landing-zone`, `gcp/landing-zone`, and `azure/landing-zone`. Run
[`atmos scaffold list`](/cli/commands/scaffold/list) to see the complete catalog, including
configured and remote sources available to the current project.

`basic` is a small cloud-agnostic project with a real local greeting component. `aws/app` starts
an application SDLC layout with development, staging, and production stacks. The landing-zone
templates establish cloud-specific platform foundations.

`[template]` also accepts a direct source instead of a catalog name — a local path, git, HTTPS,
S3, or an OCI registry reference:

```shell
atmos init oci://ghcr.io/example/templates:v1.0.0 ./my-project
```

An OCI source is pulled the same way `atmos vendor pull` fetches OCI-hosted components; see
[Vendor URL Syntax](/vendor/url-syntax#oci-syntax) for authentication details.

## Shared Scaffold Contract

Project templates use the same `AtmosScaffoldConfig` manifest and generation engine as
[`atmos scaffold generate`](/cli/commands/scaffold/generate). A template can define validated
`spec.fields`, conditional `spec.files`, and step-backed `spec.hooks`:

```yaml title="scaffold.yaml"
apiVersion: atmos/v1
kind: AtmosScaffoldConfig
metadata:
  name: application-project
spec:
  fields:
    - name: environments
      type: multiselect
      options: [dev, staging, prod]
      default: [dev]
    - name: enable_monitoring
      type: confirm
      default: false
  files:
    - path: monitoring.tf
      when: "answers.enable_monitoring == true"
  hooks:
    format:
      events: [after.scaffold.generate]
      kind: step
      type: shell
      with:
        command: terraform fmt -recursive
```

Conditions use `when:` predicates or CEL over earlier `answers`. Generation hooks can use only
`kind: step` and ordered `kind: steps`; see [scaffold templates](/cli/commands/scaffold/usage) for the
complete authoring model, including `--skip-hooks` and answer templating.

An unset (or bare-relative) `working_directory:` on a hook step defaults to the generated
project's target directory, so `terraform fmt -recursive` above runs against the generated files
even when the target differs from the directory `atmos` was launched from. Set
`working_directory: "."` to opt back into running the hook in the original working directory. A
`type: atmos` step is exempt from this default: it keeps running in the directory `atmos` was
launched from when `working_directory:` is unset, since the nested `atmos` invocation must resolve
its own config there, but an explicit `working_directory:` on that step is still honored.

## Updating an Initialized Project

`init` records the selected source, base revision, and answers in `.atmos/scaffold.yaml`. Re-run
with `--update` to bring an existing project forward using an optimistic three-way merge:

```shell
cd my-project
atmos init --update
atmos init --update --merge-strategy=theirs
atmos init --update --update-strategy=rendered
```

`manual` is the default merge strategy and surfaces conflicts. `ours` preserves local changes;
`theirs` applies the template side of a conflict. `atmos init` creates Git history by default; pass
`--no-git` when that is not wanted.

`--update-strategy` controls where the merge's _base_ comes from — an independent choice from
`--merge-strategy`. `tracked` (the default) reads it from the project's own Git history at
`--base-ref`. `rendered` instead re-renders the template at the ref that produced what's currently
on disk, using that generation's recorded answers, without requiring the target project's Git history. This
needs two separate things, not one: the template itself must define a `scaffold.yaml` manifest (so
the old ref's fields can be resolved when re-rendering), and the project must already carry a prior
generation's `.atmos/scaffold.yaml` record (a different file, at a different path — it stores that
generation's recorded answers, not the template's field definitions).

## Flags and Automation

- **`--set key=value` (repeatable)**
  Provide a template answer; repeat for multiple fields.
- **`--interactive=false`**
  Run without form prompts when values and defaults satisfy active fields.
- **`--force`**
  Permit writes into an existing target.
- **`--update`**
  Merge a generated project with its template's newer revision.
- **`--base-ref`**

  Override the recorded merge base. Only applies to `--update-strategy=tracked` — `rendered`'s
  base comes from the project's own recorded `.atmos/scaffold.yaml`, not `--base-ref`. Combining
  `--base-ref` with `--update-strategy=rendered` is rejected; drop `--base-ref` when using
  `rendered`.
- **`--update-strategy` (default `tracked`)**

  Choose where `--update`'s three-way merge base comes from. `tracked` reads it from the
  project's own Git history at `--base-ref`. `rendered` instead re-renders the template at the
  ref that produced what's currently on disk, using that generation's recorded answers, with no
  dependency on Git history at all. This needs the template itself to define a `scaffold.yaml`
  manifest (so the old ref's fields can be resolved) and the project to already carry a prior
  generation's `.atmos/scaffold.yaml` record (so the original answers are recoverable) — two
  separate files, not one.
- **`--merge-driver` (default `auto`)**

  Choose `auto` (YAML-aware for `.yaml`/`.yml`, text otherwise) or `text` to force every file
  through the line-oriented text merge driver, preserving formatting (e.g. blank lines) that a
  YAML-aware re-encode would otherwise collapse.
- **`--merge-strategy`**
  Select 
  `manual`
  , 
  `ours`
  , or 
  `theirs`
  .
- **`--skip-hooks`**
  Skip all hooks or named generation hooks.
- **`--no-git`**
  Do not initialize or commit Git history.

## Related Commands

- [Scaffold templates](/cli/commands/scaffold/usage)
- [`atmos scaffold generate`](/cli/commands/scaffold/generate)
- [`atmos scaffold validate`](/cli/commands/scaffold/validate)