# Writing a config

> Every key of the zc-workstation config file, per provider.

The config is found in this order: `-config`, `$ZC_WORKSTATION_CONFIG`, `./zc-workstation.yaml`, then `~/.config/zc-workstation/zc-workstation.yaml`. `-config -` reads standard input.

Keep the config in your dotfiles repository next to the manifests it names. Relative paths are relative to the config file, and `~` is your home directory, so the same file works on every machine.

```yaml
version: 1
targets:
  - name: brew
    provider: packages
    os: [darwin]
    file: packages/Brewfile

  - name: dotfiles
    provider: dotfiles
    source: home
    mode: symlink

  - name: runtimes
    provider: tools
    file: mise.toml
```

## Every target

 
| Key | Meaning |
| --- | --- |
| 
`version`

 | 

Always `1`. A future format bumps it.

 |
| 

`name`

 | 

Lowercase kebab case, unique. `-target` selects by it.

 |
| 

`provider`

 | 

`packages`, `dotfiles`, `tools`, `desktop`, `settings`, `services`, `keyboard`, `agents` or `localdir`.

 |
| 

`os`

 | 

The systems the target is for: `darwin`, `linux`, `windows`. Empty means every system.

 |

## Per provider

  
| Provider | Key | Meaning |
| --- | --- | --- |
| 
`packages`

 | 

`file`

 | 

Required. The manifest: a Brewfile, a package list, or a winget import file.

 |
|  | 

`manager`

 | 

`brew`, `apt`, `dnf` or `winget`. Empty picks the system’s: brew on macOS, winget on Windows, apt on Linux unless only dnf is installed.

 |
|  | 

`upgrade`

 | 

Also plan an `UPDATE` for each declared package with a newer version. Off by default.

 |
| 

`dotfiles`

 | 

`source`

 | 

Required. The chezmoi source directory.

 |
|  | 

`destination`

 | 

Where the files land. Empty means your home directory.

 |
|  | 

`mode`

 | 

`file` copies (the default); `symlink` links back into the source.

 |
| 

`tools`

 | 

`file`

 | 

Required. The mise config file whose tools to install.

 |
|  | 

`upgrade`

 | 

Also plan an `UPDATE` for each runtime with a newer version that its request allows. Off by default.

 |
| 

`desktop`

 | 

`wallpaper`

 | 

The picture to show on every desktop.

 |
|  | 

`screensaver`

 | 

The web page for WebViewScreenSaver to show. Set this, `wallpaper`, `accent`, or any of them. The target needs `os: [darwin]`.

 |
|  | 

`accent`

 | 

The macOS accent colour: `blue`, `purple`, `pink`, `red`, `orange`, `yellow`, `green` or `graphite`.

 |
| 

`settings`

 | 

`defaults`

 | 

Required on macOS. A macOS preferences domain, such as `com.apple.dock` or `NSGlobalDomain`, to its keys and values: a bool, an integer, a number or a string. A string starting with `~/` is a path in your home directory. The target needs `os: [darwin]`.

 |
|  | 

`gsettings`

 | 

Required on Linux. A GNOME schema, such as `org.gnome.desktop.interface`, to its keys and values: a bool, a number, a string or a list of strings. The target needs `os: [linux]`.

 |
|  | 

`registry`

 | 

Required on Windows. A registry key under `HKCU`, such as `'HKCU\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize'`, to its values: a bool or an integer, stored as a DWORD, or a string. The target needs `os: [windows]`.

 |
| 

`services`

 | 

`services`

 | 

Homebrew services to keep running. Set this, `agents`, or both. The target needs `os: [darwin]` or `os: [linux]`.

 |
|  | 

`agents`

 | 

launchd agent plists to keep loaded, the label being the file name without `.plist`; on Linux, systemd user `.service` and `.timer` files to keep enabled and active; on Windows, Task Scheduler `.xml` files to keep registered and enabled. The target needs one `os`.

 |
| 

`keyboard`

 | 

`file`

 | 

Required. The keyd config to install as `/etc/keyd/default.conf`, such as `assets/keyd/default.conf`. The target needs `os: [linux]`.

 |
| 

`localdir`

 | 

`path`

 | 

Required. The directory to keep.

 |
|  | 

`files`

 | 

File name to content. Names must stay inside `path`.

 |
|  | 

`prune`

 | 

Also delete files in `path` the config does not list.

 |

[Providers](providers.html) describes what each one reads and runs.

## Mistakes are errors

An unknown key is an error, not a warning: a typo should not silently mean the default. A key a provider ignores, such as `mode` on a `packages` target, is an error too. `validate` reports every problem at once:

```console
$ zc-workstation validate
zc-workstation.yaml: target brew: manager "pacman" is not one of brew, apt, dnf, winget
target dotfiles: source is required for provider dotfiles
```