# atmos helm diff

Show a real unified diff between the chart Atmos would render and a baseline —
the currently deployed release, a local manifest file, or the manifests in your
GitOps deployment repository. The chart is rendered client-side with the Helm Go
SDK and compared with the [helm-diff](https://github.com/databus23/helm-diff)
engine, so changes read as familiar `+`/`-` lines. Secret values are redacted.

## Usage

```shell
atmos helm diff <component> --stack <stack> [options]

# Diff against the deployed release (requires cluster access).
atmos helm diff monitoring -s plat-ue2-dev

# Diff against a local baseline manifest (offline, no cluster).
atmos helm diff monitoring -s plat-ue2-dev --from-manifest=current.yaml

# Diff against the GitOps deployment repository (offline, git access only).
atmos helm diff monitoring -s plat-ue2-dev --against=target

# Preview an apply with transient Helm values.
atmos helm diff monitoring -s plat-ue2-dev -f incident-values.yaml --set image.tag=2026.09.09

# Diff all components tagged "production" (composes with --all/--affected)
atmos helm diff --all --tags production
```

## Baselines

`diff` compares the freshly rendered chart against one baseline, selected by flag
precedence (`--from-manifest` → `--against` → deployed release):

- **Deployed release (default)** — The manifest of the currently installed release, read from the cluster. A release that does not exist yet shows its template resources and any missing install-only CRDs as added. This is the only mode that needs cluster access.
- **`--from-manifest=<path>`** — A local baseline manifest file. Fully offline — no cluster, no git.
- **`--against=target[:<name>]`** — The manifests currently published in a non-cluster provision target (e.g. a git deployment repository). Reads the target's current state and diffs against it — the producer side of a GitOps workflow. Offline (git access only). Without :\<name> the provision.default target is used.

## Custom resource definitions

Release-based `diff` and `plan` follow Helm's handling of the chart's `crds/`
directory, including enabled subcharts:

- For an existing release, these install-only CRDs are omitted from the diff.
  Helm does not upgrade them or store them in the release manifest.
- For a new release, Atmos checks each CRD by name and shows only those missing
  from the cluster. This requires permission to get the chart's CRDs; lookup
  errors fail the plan rather than treating the CRDs as missing.

CRDs declared in `templates/` remain part of the normal diff because Helm manages
those resources. `helm template`, local-file comparisons, and GitOps target
comparisons continue to include the chart's full CRD manifests.

## Flags

- **`--stack`, `-s` (required)** — Atmos stack.
- **`--against=<source>` (optional)** — Baseline to diff against: release (the deployed release, default) or target\[:\<name>] for a git deployment-repo provision target.
- **`--from-manifest=<path>` (optional)** — Diff against a local baseline manifest file instead of the cluster (offline).
- **`--context=<n>` (optional)** — Number of unchanged context lines shown around each change. Defaults to 3.
- **`--dependency-update` (optional)** — Fetch declared chart dependencies when they are missing. This may access dependency repositories and update the chart's charts/ directory and lock file.
- **`-f` / `--values`, `--set`, `--set-string`, `--set-file`, `--set-json`, `--set-literal` (optional)** — Repeatable Helm-compatible value overrides for this preview. Reuse them with apply to preview the exact deployment; they do not modify stack configuration. See runtime value overrides.
- **`--all` / `--affected` / `--include-dependents` (optional)** — Process multiple Helm components in dependency order.
- **`--tags` / `--labels` (optional)** — Filter by tags (comma-separated, matches any) or labels (comma-separated `key=value` or `key:value` pairs in one flag value, matches all): `--tags=production,tier-1`, `--labels=cost-center=platform`. Compose with `--all`/`--affected` to narrow the selected set further; cannot be combined with a single component argument.

:::note
[`atmos helm plan`](/cli/commands/helm/plan) is an alias for `diff`. To render the
chart without comparing, use [`atmos helm template`](/cli/commands/helm/template).
The diff uses the helm-diff library directly — you do **not** need to install the
`helm-diff` CLI plugin.
:::

## Try it out

### helm

Copy the example into a new directory and make it your own:

```shell
atmos init examples/helm
cd helm
```

Render a baseline, then compare the chart against it offline. An unchanged example has no diff; edit replicaCount in stacks/deploy/dev.yaml to see a change.

```shell
atmos helm template demo -s dev --output baseline.yaml
atmos helm diff demo -s dev --from-manifest baseline.yaml
```

- [Installation guide](/install)
- [Explore the example](/examples/helm)
- [Initialization and repository settings](/cli/commands/init#examples-and-source-directories)
