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

# Gandalf environment variables reference

> Reference for Gandalf's environment variables: store location, experimental mutation gating, update-check opt-in, and how they interact with CLI flags.

Gandalf reads a small set of environment variables to override defaults and gate destructive operations. Every variable is optional. The CLI still requires explicit flags for mutation even when environment variables are set.

## Reference

| Variable               | Purpose                                                                                        | Default        |
| ---------------------- | ---------------------------------------------------------------------------------------------- | -------------- |
| `HOME`                 | Home directory used to locate user-scope agent files (`~/.codex/`, `~/.claude/`).              | System default |
| `GANDALF_STORE`        | Override the Gandalf store directory.                                                          | `~/.gandalf`   |
| `GANDALF_EXPERIMENTAL` | Set to `1` to enable experimental mutating operations, equivalent to passing `--experimental`. | Unset          |
| `GANDALF_UPDATE_CHECK` | Set to `1` to enable update notices.                                                           | Off            |

## HOME

Gandalf resolves user-scope evidence relative to `HOME`. Override the effective home with the `--home` flag or by setting `HOME` in your shell environment.

## GANDALF\_STORE

Points to the on-disk store for snapshots, timeline entries, and the store index. The default is `~/.gandalf`. The CLI resolution order is:

1. `--store <path>` flag.
2. `$GANDALF_STORE`.
3. Default `~/.gandalf`.

## GANDALF\_EXPERIMENTAL

Gates destructive operations. Setting `GANDALF_EXPERIMENTAL=1` is equivalent to passing `--experimental` on the affected commands. It does **not** replace the operation-specific flag: you still need `--apply` on `gandalf restore` and `--apply-content` on `gandalf bundle import`.

Effective combinations:

* `gandalf restore --snapshot <name> --apply --experimental` or `gandalf restore --snapshot <name> --apply` with `GANDALF_EXPERIMENTAL=1`.
* `gandalf bundle import <bundle> --apply-content --experimental` or `gandalf bundle import <bundle> --apply-content` with `GANDALF_EXPERIMENTAL=1`.

## GANDALF\_UPDATE\_CHECK

Update notices are off by default in line with the [Trust contract](/trust-contract). Set `GANDALF_UPDATE_CHECK=1` to opt in to update checks.

## Related

* [Trust contract](/trust-contract)
* [`gandalf restore`](/cli/restore)
* [`gandalf bundle`](/cli/bundle)