# atmos helmfile

Use these subcommands to run `helmfile` commands.

# Usage

The `helmfile` integration passes through all arguments to the `helmfile` command.

Executes `helmfile` commands.

```shell
atmos helmfile <command> <component> -s <stack> [options]
atmos helmfile <command> <component> --stack <stack> [options]
```

## Path-Based Component Resolution

Atmos supports using filesystem paths instead of component names for convenience. This allows you to navigate to a component directory and use `.` to reference it:

```shell
# Navigate to component directory
cd components/helmfile/echo-server

# Use . to reference current directory
atmos helmfile diff . -s dev
atmos helmfile apply . -s dev
```

This automatically resolves the path to the component name configured in your stack, eliminating the need to remember exact component names.

**Supported path formats:**

- `.` - Current directory
- `./component` - Relative path from current directory
- `../other-component` - Relative path to sibling directory
- `/absolute/path/to/component` - Absolute path

**Requirements:**

- Must be inside a component directory under the configured base path
- Must specify `--stack` flag
- Component must exist in the specified stack configuration
- **The component path must resolve to a unique component name** - If multiple components in the stack reference the same component path, you must use the unique component name instead of the path

:::warning Path Resolution Limitation
Path-based resolution only works when the component path resolves to a **single unique component** in the stack.

For example, if both `app/1` and `app/2` reference `components/helmfile/my-app`:

```bash
cd components/helmfile/my-app
atmos helmfile apply . --stack dev  # ❌ Error: ambiguous - which component?
```

Instead, you must use the unique component names:

```bash
atmos helmfile apply app/1 --stack dev  # ✓ Explicit and unambiguous
atmos helmfile apply app/2 --stack dev  # ✓ Explicit and unambiguous
```

:::

:::info
Atmos supports all `helmfile` commands and options described in [Helmfile CLI reference](https://github.com/helmfile/helmfile#cli-reference).

In addition, the `component` argument and `stack` flag are required to generate variables for the component in the stack.
:::

**Additions and differences from native Helmfile:**

- `atmos helmfile generate varfile` command generates a varfile for the component in the stack

- `atmos helmfile` commands support [GLOBAL OPTIONS](https://github.com/roboll/helmfile#cli-reference) using the command-line flag `--global-options`.
  Usage: `atmos helmfile <command> <component> -s <stack> [command options] [arguments] --global-options="--no-color --namespace=test"`

- before executing the `helmfile` commands, Atmos runs `aws eks update-kubeconfig` to read kubeconfig from the EKS cluster and use it to
  authenticate with the cluster. This can be disabled in `atmos.yaml` CLI config by setting `components.helmfile.use_eks` to `false`

- double-dash `--` can be used to signify the end of the options for Atmos and the start of the additional native arguments and flags for
  the `helmfile` commands.

:::tip
Run `atmos helmfile --help` to see all the available options
:::

## Examples

### Component Name Examples

```shell
atmos helmfile diff echo-server -s tenant1-ue2-dev
atmos helmfile diff echo-server -s tenant1-ue2-dev --redirect-stderr /dev/null

atmos helmfile apply echo-server -s tenant1-ue2-dev
atmos helmfile apply echo-server -s tenant1-ue2-dev --redirect-stderr /dev/stdout

atmos helmfile sync echo-server --stack tenant1-ue2-dev
atmos helmfile sync echo-server --stack tenant1-ue2-dev --redirect-stderr ./errors.txt

atmos helmfile destroy echo-server --stack=tenant1-ue2-dev
atmos helmfile destroy echo-server --stack=tenant1-ue2-dev --redirect-stderr /dev/stdout
```

### Path-Based Examples

```shell
# Navigate to component directory and use current directory
cd components/helmfile/echo-server
atmos helmfile diff . -s dev
atmos helmfile apply . -s dev

# Use relative path from components/helmfile directory
cd components/helmfile
atmos helmfile sync ./echo-server -s prod

# Use from project root with relative path
atmos helmfile apply components/helmfile/echo-server -s dev

# Combine with other flags
cd components/helmfile/echo-server
atmos helmfile diff . -s dev --redirect-stderr /dev/null
atmos helmfile sync . -s dev --global-options="--no-color"
```

## Arguments

- **`component` (required)**

  Atmos component name or filesystem path.
  Supports both:

  Component names: echo-server, apps/nginx
  Filesystem paths: . (current directory), ./echo-server, components/helmfile/echo-server

  When using paths, Atmos automatically resolves the path to the component name based on your stack configuration.
  See Path-Based Component Resolution above.

## Flags

- **`--stack` / `-s` (required)**
  Atmos stack.
- **`--dry-run` (optional)**
  Dry run.
- **`--redirect-stderr` (optional)**
  File descriptor to redirect 
  `stderr`
   to.
  Errors can be redirected to any file or any standard file descriptor
  (including 
  `/dev/null`
  ).

:::note

All native `helmfile` flags, command options, and arguments are supported

:::

**Configure Helmfile**

Learn how to configure Helmfile components in your `atmos.yaml`, including EKS integration and kubeconfig settings.

## Subcommands