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
    },
    "screen_recording": {
        "include_audio": true
    },
    "idle": {
        "lock_timeout": 3600,
        "ignore_dbus_inhibit": false,
        "ignore_systemd_inhibit": false,
        "ignore_wayland_inhibit": false,
        "inhibit_sleep": 2,

        "listeners": {}
    },
    "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 about them on GitHub)

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

screen_recording

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

Properties:

include_audio

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

idle

• Type: object
• Description: Idle daemon configuration. Colorshell wraps hypridle behind the scenes to do the work.

Properties:

lock_timeout

• Type: number
• Description: Idle timeout in seconds for the session to be locked(uses hyprlock)
• Default: 3600 (1 hour)

listeners

• Type: object of object
• Description: List of custom idle listeners for hypridle. Add one in this format: "listener_name": { "timeout": 1200, "on_timeout": "notify-send test 'listener notified!'" }
• Default: {}

Other properties

They're the same as in the Hyprland Wiki/hypridle (custom listeners are an exception) You can add custom listeners by using the idle:listeners property.

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