Configuration

This page is a documentation for colorshell's configuration file, located on XDG_CONFIG_HOME/colorshell/config.json.

Example Configuration

Usually, colorshell will write a default config if it doesn't exist in your user config directory: XDG_CONFIG_HOME/colorshell/config.json or ~/.config/colorshell/config.json.

config.example.json

{
    "notifications": {
        "timeout_low": 4000,
        "timeout_normal": 6000,
        "timeout_critical": 0,
        "position_h": "right",
        "position_v": "top",
        "dismiss_on_unhover": false,
        "hold_on_hover": true
    },
    "night_light": {
        "save_on_shutdown": true
    },
    "wallpaper": {
        "positioning": "cover",
        "splash": true
    },
    "color": {
        "backend": "default"
    },
    "workspaces": {
        "always_show_id": false,
        "enable_helper": true,
        "hide_if_single": false
    },
    "screen_recording": {
        "include_audio": true
    },
    "aliases": {
        "terminal": "kitty",
        "file_manager": "nautilus",
        "media": "amberol"
    },
    "runner": {
        "search_on_open": false,
        "max_results": 24,
        "ignore_empty_search": true,
        "show_tips": true
    },
    "clock": {
        "date_format": "%A %d, %H:%M"
    },
    "misc": {
        "match_window_border_color": true,
        "play_bell_on_volume_change": true
    }
}

Entries

Note

Property names and locations are subject to change, so keep an eye on breaking changes!
(You can also subscribe to the issue to receive notifications about them on GitHub)

notifications

• Type: object
• Description: Configure notification timeouts, position and other features.

timeout_low

• Type: number
• Description: Low-priority notification timeout in milliseconds
• Default: 4000

timeout_normal

• Type: number
• Description: Common notification timeout in milliseconds
• Default: 6000

timeout_critical

• Type: number
• Description: Critical notification timeout in milliseconds (0ms makes the notification stay, until manual dismiss)
• Default: 0

position_h

• Type: string
• Description: Horizontal position of the notification popup
• Values: "left", "center" or "right"
• Default: "right"

position_v

• Type: string
• Description: Vertical position of the notification popup
• Values: "top", "center" or "bottom"
• Default: "top"

dismiss_on_unhover

• Type: boolean
• Description: Whether to instantly dismiss the notification after unhovering the popup
• Default: false

hold_on_hover

• Type: boolean
• Description: Whether to pause the notification timeout while hovering the notification
• Default: true

night_light

• Type: object
• Description: Configure the hyprsunset blue-light filter

save_on_shutdown

• Type: boolean
• Description: Whether to save the night light temperature and gamma properties on disk on power/session actions(suspend, log out, power off, reboot)
• Default: true

wallpaper

• Type: object
• Description: Configure wallpaper placement and color generation options

positioning

• Type: string
• Description: Wallpaper positioning method
• Values: "fill", "cover", "contain" or "tile"
• Default: "cover"

splash

• Type: boolean
• Description: Whether to enable Hyprland's random splash text to render on the wallpaper
• Default: true

color

• Type: object
• Description: Modify color engine settings

backend

• Type: string
• Description: The color engine's preferred backend
• Default: "default"
• Options: "wal"(default), "colorthief", "modern_colorthief", "haishoku"... (see wal --backend for a complete list)

workspaces

• Type: object
• Description: Configure the workspace indicator widget of the top bar

always_show_id

• Type: boolean
• Description: Whether to always show the workspace ID(number) in the workspace indicators
• Default: false

enable_helper

• Type: boolean
• Description: Whether to enable colorshell's Workspace Helper, which automatically shows the workspace ID for better navigation between distant workspaces (e.g.: if there are only two workspaces(1 and 5), colorshell will automatically reveal the 5th workspace ID for better keyboard navigation(only if workspaces:always_show_id is disabled))
• Default: true

hide_if_single

• Type: boolean
• Description: Whether to hide the workspaces indicator widget if there's only a single workspace in use
• Default: false

screen_recording

• Type: object
• Description: Configure the screen recorder behavior.

include_audio

• Type: boolean
• Description: Whether to include desktop audio in the screen recording
• Default: true

aliases

• Type: object
• Description: App/Command alias list. This is internally used to launch default applications, like file_manager, terminal and media. But you can also add your own custom aliases. (p.s.: You can manually launch these aliases with colorshell run -a alias_name)

Default entries:

terminal

• Type: string
• Description: Default terminal command
• Default: "kitty"

file_manager

• Type: string
• Description: Default file manager command
• Default: "nautilus"

media

• Type: string
• Description: Default media player command
• Default: "amberol"

runner

• Type: object
• Description: Tinker with the Multi-functional Runner's behavior

search_on_open

• Type: boolean
• Description: Whether to search upon opening the runner(useful with runner:ignore_empty_search to show results on open)
• Default: false

max_results

• Type: number
• Description: Limit of search results. Set to 0 for unlimited
• Default: 24

ignore_empty_search

• Type: boolean
• Description: Whether to skip searching if the search string(text) is empty
• Default: true

show_tips

• Type: boolean
• Description: Whether to show placeholder results with tips on usage when the search is empty, or when there aren't results for the current search. Conflicts with runner:ignore_empty_search(if both enabled, tips won't show when search is empty)
• Default: true

clock

• Type: object
• Description: Clock format configurations

date_format

• Type: string
• Description: The top bar clock format (uses the same gnu's date format, see here)
• Default: "%A %d, %H:%M"

misc

• Type: object
• Description: Miscellaneous options to tweak shell features

match_window_border_color

• Type: boolean
• Description: Whether to match window's border color with the shell's color scheme
• Default: true

play_bell_on_volume_change

• Type: boolean
• Description: Whether to play a bell sound effect on volume change(increase/decrease)
• Default: true