Configuring Vicinae

Vicinae can be configured using either the GUI or its configuration file. This document presents a brief overview of how configuration works in vicinae.

GUI Configuration

Vicinae is intended to be fully customizable using the GUI.

There are two main ways to do so:

• Through built-in commands, which may write to the configuration in some circumstances (e.g "Set Theme" command)
• Through the dedicated settings window, which can be opened using the ctrl-' keybind or by activating the "Open Settings" built-in command

More intricate settings are only configurable by editing the config file directly, more on that below.

Configuration file

All the configurable vicinae settings are serialized in JSONC format (JSON with comments).

Vicinae starts by loading its default configuration, which can be obtained by running the following command:

vicinae config default

Then, the user config file (located at ~/.config/vicinae/settings.json by default) is read and merged with the default configuration file, overriding any default value.

This user config file needs to be readable and writable as most configuration changes made through the GUI will be written to it. If you're dealing with a read-only config , the recommended approach is to use imports as described below.

Config imports

It is possible to split up configuration by importing other config files from the main user config file.

To do so, you simply need to add the files to import to the imports array. Files imported in this way are merged before the main user configuration file is considered and are never touched by vicinae directly, allowing them to be freely formatted and annotated with custom comments.

{
	"imports": [
		"base_config.json",
		"keybinds.json"
	],

	// remaining configuration...
}

Config documentation

All config options are thoroughly documented in the default configuration file.

Config exclusions

Extension preferences of type 'password' are not written to the config file because they are treated as sensitive data. They are stored in the internal sqlite database instead, which will become fully encryptable in the future.

Migration from v0.16.X to v0.17.X

The overhaul of the configuration system is a huge breaking change: users will need to redo their configuration, either by migrating their old file to the new format by hand or simply by reconfiguring using the GUI.

Provider data (preferences, aliases, etc...) went from being stored in the internal database to being stored in the config file, so there is no easy way to migrate them over. Just use the GUI and let it write the values to the file for you.

The file at ~/.config/vicinae/vicinae.json is no longer read by vicinae and can be removed, superseded by the ~/.config/vicinae/settings.json file.