Configuration file reference

brush supports an optional TOML configuration file that allows you to customize shell behavior without command-line arguments.

File Location

brush looks for the configuration file at:

• Linux/macOS: ${XDG_CONFIG_HOME}/brush/config.toml*
• Windows: %APPDATA%\brush\config.toml

Note

On Linux/macOS falls back to ~/.config/brush/config.toml if XDG_CONFIG_HOME is undefined.

You can override this location with the --config flag:

brush --config /path/to/custom/config.toml

To disable configuration file loading entirely, use:

brush --no-config

Configuration Priority

Settings are applied in the following order (later values override earlier ones):

1. Defaults - Built-in default values
2. Configuration file - Values from config.toml
3. Command-line arguments - Flags passed to brush

File Format

The configuration file uses TOML format. All settings are optional; brush uses sensible defaults for any unspecified values.

Example Configuration

[ui]
syntax-highlighting = true

[experimental]
zsh-hooks = true
terminal-shell-integration = true

Available Settings

[ui] Section

User interface settings.

Setting	Type	Default	CLI flag	Description
syntax-highlighting	boolean	see below	--enable-highlighting	Enable syntax highlighting in the input line

The default value of syntax-highlighting depends on how brush-shell was built: true when built with the experimental Cargo feature, false otherwise. CLI flags take precedence over the configuration file.

[experimental] Section

Experimental features that may change or be removed in future versions. Each setting has an equivalent command-line flag; CLI flags take precedence over the configuration file. See the experimental features reference for details on each feature.

Setting	Type	Default	CLI flag	Description
zsh-hooks	boolean	false	--enable-zsh-hooks	Enable zsh-style preexec/precmd hooks
terminal-shell-integration	boolean	false	--enable-terminal-integration	Enable terminal shell integration

JSON Schema

A JSON Schema for the configuration file is available at schemas/config.schema.json. This can be used with editors that support schema-based validation and autocompletion for TOML files.

Using the Schema with VS Code

To enable schema validation in VS Code with the Even Better TOML extension, add this to your config.toml:

#:schema https://raw.githubusercontent.com/reubeno/brush/main/schemas/config.schema.json

[ui]
syntax-highlighting = true

The #:schema directive tells the editor where to find the schema for validation and autocompletion.

Using the Schema with Other Editors

Many editors support JSON Schema for TOML files. Consult your editor’s documentation for how to associate a schema with a file. You can reference the schema via:

• URL: https://raw.githubusercontent.com/reubeno/brush/main/schemas/config.schema.json
• Local path: Point to schemas/config.schema.json in your brush source checkout

Sample Configuration

A sample configuration file is available at samples/config.toml in the brush repository. You can copy this file to get started:

# Linux/macOS
mkdir -p ~/.config/brush
cp samples/config.toml ~/.config/brush/config.toml

Forward Compatibility

brush ignores unknown settings in the configuration file. This allows configuration files to be shared across different versions of brush without causing errors.

Error Handling

If the configuration file cannot be read or parsed, brush logs an error message and continues with default settings. The shell will still start normally.

---

Describes brush v0.4.0. Maintained upstream as docs/reference/configuration.md; later changes on main may not be reflected here yet.