Vicinae

CLI Tools

The vicinae binary provides command-line tools for managing, validating, and debugging theme files.

Available Commands

Run the following to see all theme-related commands:

vicinae theme --help

This will display the available subcommands and their options.

Generate Theme Template

Create a theme template to start from:

vicinae theme template > ~/.local/share/vicinae/themes/my-new-theme.toml

On Windows, use %LOCALAPPDATA%\vicinae\data\themes instead.

This command outputs a template to stdout, which you can redirect to a file. The template includes:

  • All available metadata fields
  • The most common color tables and keys
  • Example values

Set Active Theme

Change the currently active theme from the command line:

vicinae theme set <theme_id>

The theme_id is the theme filename without the .toml extension. For example, if your theme file is named catppuccin-mocha.toml, use:

vicinae theme set catppuccin-mocha

Typical Search Paths

On Linux, the paths follow the XDG Base Directory specification:

  1. ~/.local/share/vicinae/themes (user themes)
  2. /usr/local/share/vicinae/themes (system-wide themes)
  3. /usr/share/vicinae/themes (distribution themes)

On macOS:

  1. ~/.local/share/vicinae/themes (user themes)
  2. Vicinae.app/Contents/Resources/themes (bundled themes)

On Windows:

  1. %LOCALAPPDATA%\vicinae\data\themes (user themes)
  2. themes in the Vicinae install directory (bundled themes)

Always place custom themes in the user themes directory to avoid conflicts with updates.

Theme Shadowing

If two themes have the same filename in different search paths, only the first one will be loaded. This allows you to override system themes with custom versions:

~/.local/share/vicinae/themes/rose-pine.toml  ← This one loads
/usr/share/vicinae/themes/rose-pine.toml      ← This one is shadowed

Theme Directory Structure

Theme directories must be flat - subdirectories are not searched. All theme files should be placed directly in the theme directory:

Correct:
~/.local/share/vicinae/themes/
├── my-theme.toml
├── another-theme.toml
└── catppuccin-mocha.toml

Incorrect (subdirectories won't be found):
~/.local/share/vicinae/themes/
└── custom/
    └── my-theme.toml

However, theme assets (like icons) can be in subdirectories and referenced relatively:

[meta]
icon = "icons/my-theme-icon.png"

This will look for icons/my-theme-icon.png relative to the theme file's location.

Theme directories are automatically watched. Changes to theme files are applied immediately without restarting Vicinae.

Next Steps