# Configuration Overview
Jay is configured through a single TOML file located at:
```
~/.config/jay/config.toml
```
If this file does not exist, Jay uses built-in defaults that provide a
reasonable starting configuration with common shortcuts, a US QWERTY keymap,
and other sensible settings.
> [!WARNING]
> Once `config.toml` exists, the **entire** built-in default configuration is
> replaced -- not merged. Even a completely empty file means no shortcuts, no
> startup actions, nothing. Always start from a full config rather than writing
> one from scratch.
## Initializing the config
The easiest way to get started is to let Jay write the defaults for you:
```shell
~$ jay config init
```
This creates `~/.config/jay/config.toml` pre-populated with the full default
configuration. You can then edit it to suit your needs.
If you already have a config file and want to reset it:
```shell
~$ jay config init --overwrite
```
The old file will be backed up to `config.toml.1` (or `.2`, `.3`, etc.) before
being replaced.
## Other config subcommands
Print the path to the config file:
```shell
~$ jay config path
```
Open the config directory in your file manager:
```shell
~$ jay config open-dir
```
## Reloading the configuration
By default, Jay does not automatically reload `config.toml` when it changes on
disk. To apply changes, trigger a reload manually:
- Press `alt-shift-r` (the default shortcut), or
- Use the `reload-config-toml` action in any other action context (e.g. a named
action or a window rule).
Most settings take effect immediately on reload. A few exceptions (like
`log-level`, `explicit-sync`, and initial `drm-devices` settings) only apply
at compositor startup.
### Automatic reloading
To have Jay watch `config.toml` for changes and reload automatically, add:
```toml
auto-reload = true
```
When enabled, Jay uses inotify to monitor the config file and its parent
directories. Changes are debounced — the config is reloaded 400 ms after the
last write, so rapid successive saves don't cause multiple reloads. If the file
contents haven't actually changed, the reload is skipped.
Setting `auto-reload = false` will stop the watcher. Removing the key entirely
leaves the watcher state unchanged (if it was running, it keeps running until
the compositor restarts).
## Named actions
You can define reusable actions in the `[actions]` table and reference them
anywhere an action is accepted by prefixing the name with `$`:
```toml
[actions]
launch-terminal = { type = "exec", exec = "alacritty" }
launch-browser = { type = "exec", exec = "firefox" }
[shortcuts]
alt-Return = "$launch-terminal"
alt-b = "$launch-browser"
```
Named actions can reference other named actions. The `max-action-depth` setting
controls the maximum recursion depth to prevent infinite loops (default: 16):
```toml
max-action-depth = 32
```
## Composable actions
Anywhere an action is accepted, you can use an **array of actions** instead.
This applies to shortcuts, startup hooks, named actions, and any other action
field:
```toml
[shortcuts]
alt-q = [
{ type = "exec", exec = ["notify-send", "Goodbye!"] },
"quit",
]
```
## Advanced: shared library configuration
For users who need programmatic configuration beyond what TOML offers, Jay also
supports configuration via a compiled Rust shared library using the
[jay-config](https://docs.rs/jay-config) crate. This is an advanced option --
the TOML config is sufficient for the vast majority of use cases.
## Full specification
This book covers the most common configuration options with explanations and
examples. For an exhaustive listing of every field, type, and action, see the
[auto-generated specification](https://github.com/mahkoh/jay/blob/master/toml-spec/spec/spec.generated.md).