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",
        "color_mode": "darken",
        "splash": true
    },
    "workspaces": {
        "always_show_id": false,
        "enable_helper": true,
        "hide_if_single": false
    },
    "aliases": {
        "terminal": "kitty",
        "file_manager": "nautilus",
        "media": "amberol"
    },
    "clock": {
        "date_format": "%A %d, %H:%M"
    },
    "misc": {
        "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)

notifications

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

Properties:

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

Properties:

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

Properties:

positioning

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

color_mode

• Type: string
• Description: Color generation mode
• Values: "darken" or "lighten"
• Default: "darken"

splash

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

workspaces

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

Properties:

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

aliases

• Type: object
• Description: App/Command alias list. This is internally used to launch default applications, like file_manager with the SUPER + E bind, terminal for the default terminal and media for the default media player. But you can also add your own aliases for you to use in your user config.(p.s.: You can manually launch these aliases with colorshell run %alias_name(keep the % character for aliases))

Default properties:

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"

clock

• Type: object
• Description: Clock format configurations

Properties:

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

Properties:

play_bell_on_volume_change

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