dotfiles/docs/chezmoi/config.mdx

---
title: Config and roles
description: The .chezmoi.toml.tmpl config template, its three prompts, symlink mode, age encryption, and where the resulting data is used.
---

`.chezmoi.toml.tmpl` is rendered once by `chezmoi init` into `~/.config/chezmoi/chezmoi.toml`. It asks three questions, turns on symlink mode and age encryption, and stores the answers as template data for every other `.tmpl` file.

## Source

```toml .chezmoi.toml.tmpl
{{- $name := promptStringOnce . "name" "Full name" "Prad Nukala" -}}
{{- $email := promptStringOnce . "email" "Email" "prad@sonr.io" -}}
{{- $roleDefault := "desktop" -}}
{{- if eq .chezmoi.os "darwin" -}}{{- $roleDefault = "mac" -}}{{- end -}}
{{- $role := promptChoiceOnce . "role" "Machine role" (list "desktop" "laptop" "mac" "server") $roleDefault -}}

mode = "symlink"
encryption = "age"

[age]
    identity = "~/.config/chezmoi/key.txt"
    recipient = "age19tdqgavaekhvgqsd75n8a09vvshen2ykzy8kw6tenczz73449anqc3l7a6"
    useBuiltin = true

[data]
    name = {{ $name | quote }}
    email = {{ $email | quote }}
    role = {{ $role | quote }}
```

## Prompts

| Key | Prompt | Type | Default |
| --- | --- | --- | --- |
| `name` | `Full name` | `promptStringOnce` | `Prad Nukala` |
| `email` | `Email` | `promptStringOnce` | `prad@sonr.io` |
| `role` | `Machine role` | `promptChoiceOnce` from `desktop`, `laptop`, `mac`, `server` | `mac` when `.chezmoi.os` is `darwin`, otherwise `desktop` |

The `*Once` functions only prompt when the key is missing from the existing config, so re-running `chezmoi init` keeps earlier answers. `chezmoi init --prompt` forces all three prompts again. Changing the role changes the rendered ignore file and package script, so the next `chezmoi apply` adds or drops the desktop layer and re-runs the package install.

### Machine roles

| Role | Intended platform | Linux desktop layer | Desktop packages (`packages.arch.desktop`) |
| --- | --- | --- | --- |
| `desktop` | Arch Linux | Applied | Installed |
| `laptop` | Arch Linux | Applied | Installed |
| `mac` | macOS | Skipped | n/a (Homebrew list only) |
| `server` | Arch Linux, headless | Skipped | Skipped |

`desktop` and `laptop` behave identically in the current templates; nothing branches on one without the other. The desktop layer is also skipped whenever the OS is not Linux, whatever the role. See [the ignore rules](/chezmoi/externals-and-ignore#chezmoiignore) for the exact list of gated paths.

## Mode

`mode = "symlink"` makes `chezmoi apply` link plain files in `$HOME` back to the source tree. Templates, `private_`, `executable_`, and encrypted files are still written as real files. The [overview](/chezmoi#symlink-mode) covers the editing consequences.

## Age encryption

| Setting | Value | Effect |
| --- | --- | --- |
| `encryption` | `"age"` | `chezmoi add --encrypt` and `encrypted_` source files use age. |
| `age.identity` | `~/.config/chezmoi/key.txt` | Private key used to decrypt. Distributed by hand between machines, never committed. |
| `age.recipient` | `age19tdqgavaekhvgqsd75n8a09vvshen2ykzy8kw6tenczz73449anqc3l7a6` | Public key files are encrypted to. Safe to publish. |
| `age.useBuiltin` | `true` | Uses chezmoi's built-in age implementation; the `age` binary is not required. |

No source file currently carries the `encrypted_` attribute, so the key is only exercised when a secret is added with `chezmoi add --encrypt`. The README still asks for the key to be copied into place before the first apply:

```sh
mkdir -p ~/.config/chezmoi
scp <existing-machine>:.config/chezmoi/key.txt ~/.config/chezmoi/key.txt
chmod 600 ~/.config/chezmoi/key.txt
```

## Template data

The `[data]` table exposes `.name`, `.email`, and `.role` to every template. chezmoi also merges `.chezmoidata/*.yaml` into the same namespace (`.packages`, `.aliases`; see [Packages and aliases](/chezmoi/data)) and provides built-ins such as `.chezmoi.os`.

| Variable | Consumed by | Use |
| --- | --- | --- |
| `.name` | `dot_gitconfig.tmpl` | `[user] name` in `~/.gitconfig` |
| `.email` | `dot_gitconfig.tmpl` | `[user] email` in `~/.gitconfig` |
| `.role` | `.chezmoiignore.tmpl` | Skips the Linux desktop layer unless role is `desktop` or `laptop` |
| `.role` | `.chezmoiscripts/run_onchange_before_10-packages.sh.tmpl` | Adds the `arch.desktop` pacman and AUR packages for `desktop`/`laptop` |
| `.chezmoi.os` | `.chezmoi.toml.tmpl` | Role default (`mac` on darwin) |
| `.chezmoi.os` | `.chezmoiignore.tmpl` | Desktop layer requires `linux` |
| `.chezmoi.os` | `run_onchange_before_10-packages.sh.tmpl` | pacman/yay on `linux`, Homebrew on `darwin` |
| `.chezmoi.os` | `run_once_after_30-user-services.sh.tmpl` | systemd user units on `linux` only |
| `.chezmoi.os` | `run_onchange_after_40-post.sh.tmpl` | `fc-cache` on `linux` only |
| `.chezmoi.os`, `.role` | `run_onchange_after_15-tools.sh.tmpl` | strata install on `linux` with role `desktop`/`laptop` |

```ini dot_gitconfig.tmpl
[user]
	email = {{ .email }}
	name = {{ .name }}
```

The rest of `~/.gitconfig` is covered under [Tools](/tools).