> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan and Apply

> Review, apply, and recover EDK changes.

<Warning>
  **Limited Release.** The EDK is currently in limited release and is not available to all customers. Commands, generated file layouts, and package APIs may change before general availability. Confirm you're on the latest EDK version before starting new projects.
</Warning>

The EDK compares authored TypeScript with state and the live Elementum target, then shows the changes required to make them match.

## Plan and apply workflow

Run the workflow from the marked `<instance>/<organization>` workspace:

```bash theme={null}
npx tsc --noEmit
elementum plan
elementum apply
elementum plan
```

Each command has a distinct purpose:

1. `npx tsc --noEmit` checks TypeScript without generating JavaScript.
2. `elementum plan` builds the current source, then previews the EDK changes for the selected Elementum target.
3. `elementum apply` builds again, then applies the reviewed changes.
4. A final `elementum plan` should report no changes.

You do not need to run `elementum build` before `plan` or `apply`. Use it when you want to generate and inspect `.tf/out/` without contacting the platform. Use `--skip-build` only when you deliberately want `plan` or `apply` to use the existing `.tf/out/` output.

## Review the complete workspace

`plan` and `apply` always operate on the full organization workspace. You can pass the organization root or any nested path:

```bash theme={null}
elementum plan
elementum plan apps/intake/intake.ts
```

The nested path only helps locate the marked organization root. It does not limit the plan to one App, Element, or file.

Before applying, account for every reported operation:

* **Add** creates a resource that is configured but not bound in state.
* **Change** updates a resource in place. The plan may instead report a replacement when the changed property cannot be updated.
* **Destroy** removes a resource that remains in state but is absent from the built configuration.

Unexpected replacements and destroys are blockers. Resolve them before applying.

## Apply and confirm the result

Apply only the plan you reviewed:

```bash theme={null}
elementum apply
```

Then plan again:

```bash theme={null}
elementum plan
```

A converged workspace produces a zero-change plan. If the EDK still proposes changes, do not repeatedly apply. Compare the remaining diff with the authored source, generated diagnostics, selected profile, and backend binding.

## Backend and state

Behind the EDK workflow, OpenTofu state provides the durable mapping between authored labels and live Elementum objects. Losing or using the wrong state can make existing objects appear new.

For compatibility, an organization workspace without `backend.tf` uses a committed root `terraform.tfstate` through a generated local backend. This supports a single-author workspace but does not provide locking. Avoid concurrent plans or applies.

Shared workspaces and CI should commit a non-secret `<orgRoot>/backend.tf` that declares a remote backend with verified locking. During build, the EDK copies that declaration to `.tf/out/backend.tf`. The backend locks state during plans, applies, pulls, renames, and repairs.

Never commit:

* `.tf/` or `.terraform/`
* Backend credentials
* Saved plan files
* Recovery snapshots

Keep credentials in the backend's normal environment or workload-identity chain. EDK does not provision backend infrastructure and does not accept secrets in `backend.tf`.

## Migrate or recover state

Use the guarded migration command when moving local state to a declared remote backend or changing remote backends:

```bash theme={null}
elementum migrate backend <orgRoot> --check
elementum migrate backend <orgRoot> --dry-run
elementum migrate backend <orgRoot> --auto-approve
elementum plan <orgRoot>
```

The migration creates an ignored recovery snapshot, verifies the result, and requires a final zero-change plan. Follow the exact rollback instructions printed if it fails.

<Warning>
  If state is lost, do not run `apply`. The EDK can interpret live resources as new and attempt to create duplicates.
</Warning>

Restore the recovery snapshot when available. Otherwise, refresh organization references and re-pull each existing managed root:

```bash theme={null}
elementum --profile <profile> pull org --data-only
cd <instance>/<organization>
elementum pull app <namespace>
elementum pull element <namespace>
elementum pull table <name-or-handle>
elementum pull task <namespace>
```

Pull verifies the expected state bindings and requires a clean follow-up plan without changing the live resources.

## Apply versus environment promotion

`elementum plan` and `elementum apply` reconcile authored source with the organization and environment selected by authentication. They do not perform Elementum's cross-environment promotion workflow.

After testing an EDK change in a lower environment, use the platform promotion workflow to move it to another environment. If the promotion reports missing environment configuration, the `/elementum-deployments` playbook can review and configure it from the admin URL or `asyncTaskId`.

See [Authentication](/edk/authentication) for target selection and [Playbooks](/edk/playbooks) for the promotion and UAT playbooks.