Caelestia & System Cheatsheet

Caelestia Override Files

All customisations go in ~/.config/caelestia/, never edit files in ~/.local/share/caelestia/.

File	Purpose
hypr-vars.conf	Override keybinding variables and app defaults
hypr-user.conf	Add/override entire Hyprland bindings, exec-once
user-config.fish	Fish shell customisations (aliases, env vars, functions)
shell.json	Shell UI config (bar, launcher, wallpaper picker, dashboard)
cli.json	CLI config (wallpaper post-hooks)

Current hypr-vars.conf

$kbTerminal = Super, Return
$browser = google-chrome-stable
$fileExplorer = nautilus

Current hypr-user.conf

exec-once = /usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1
 
# Override launcher to Super+Space
unbind = Super, Super_L
bind = Super, Space, global, caelestia:launcher

---

Keybindings

Apps

Keybind	Action
Super + Return	Terminal (foot)
Super + W	Browser (Chrome)
Super + C	Editor (Codium)
Super + E	File Explorer (Nautilus)
Super + Space	Launcher (custom override)

Window Management

Keybind	Action
Super + Q	Close window
Super + F	Fullscreen
Super + Alt + F	Bordered fullscreen
Super + Alt + Space	Toggle floating
Super + P	Pin window
Super + Z + mouse	Move window
Super + X + mouse	Resize window
Super + Left click drag	Move window
Super + Right click drag	Resize window
Super + Alt + \	Picture-in-picture

Tip: All toggles work both ways - press again to revert:

• Super + F exits fullscreen back to tiled
• Super + Alt + Space exits floating back to tiled

Resize (keyboard)

Keybind	Action
Super + -	Shrink width 10%
Super + =	Grow width 10%
Super + Shift + -	Shrink height 10%
Super + Shift + =	Grow height 10%
Super + Alt + Arrows	Resize in direction

Override percentage in hypr-user.conf with binde = Super, Minus, resizeactive, -5% 0.

Workspaces

Keybind	Action
Super + 1-9, 0	Go to workspace 1-10
Super + Alt + 1-9, 0	Move window to workspace
Ctrl + Super + Left/Right	Prev/next workspace
Super + S	Toggle special workspace

Special Workspaces

Keybind	Action
Ctrl + Shift + Escape	System monitor
Super + M	Music
Super + D	Communication
Super + R	Todo

Window Groups

Keybind	Action
Alt + Tab	Cycle next
Shift + Alt + Tab	Cycle previous
Super + Comma	Toggle group
Super + U	Ungroup

Screenshots

Keybind	Action
Print	Full screen → clipboard
Super + Shift + S	Region capture (freeze)
Super + Shift + Alt + S	Region capture

System

Keybind	Action
Ctrl + Alt + Delete	Session menu
Super + L	Lock
Super + N	Sidebar
Super + K	Show panels
Ctrl + Alt + C	Clear notifications
Ctrl + Super + Space	Media play/pause

---

Wallpapers

Default directory: ~/Pictures/Wallpapers/

# Set random wallpaper
caelestia wallpaper -r
 
# Set random, skip size filter
caelestia wallpaper -r --no-filter
 
# Set specific wallpaper
caelestia wallpaper -f ~/Pictures/Wallpapers/image.jpg
 
# Lower size threshold (default filters out images < 80% of monitor res)
caelestia wallpaper -r -t 0.5

Wallpapers must match your monitor resolution to pass the default filter.

Shell UI picker path is configured in ~/.config/caelestia/shell.json under paths.wallpaperDir.

---

Starship Prompt Symbols

Symbol	Meaning
□	Truncated path (truncation_symbol)
△	Git repo on main/master branch
◎	Last command succeeded
○	Last command failed
●◦	Modified (unstaged) files
◌◦	Untracked files
▪	Staged files
◄	Command duration

---

Fish Shell

fzf Integration

Fish does NOT support **<TAB> trigger. Use keybindings instead:

Keybind	Equivalent	Action
Ctrl + T	vim **<TAB>	Search files, insert path
Alt + C	cd **<TAB>	Search and cd into directory
Ctrl + R	history **<TAB>	Search command history

Enable with fzf --fish | source in user-config.fish.

Custom Functions

# Find file with fzf, cd to its directory
function fcd
    set file (fzf)
    and cd (dirname $file)
end
 
# Random wallpaper (no size filter)
alias wall 'caelestia wallpaper -r --no-filter'

Fish Gotchas

• No heredoc (<<EOF) support - use printf ... | sudo tee instead
• No **<TAB> fzf trigger - use Ctrl+T, Alt+C, Ctrl+R
• Scripts requiring heredocs: write as .sh and run with bash script.sh

---

Audio / PipeWire

Useful Commands

wpctl status              # Show all audio devices/streams
wpctl set-default <id>    # Set default audio source/sink
wpctl set-volume <id> 0   # Mute a device

Disable a Device via WirePlumber

Create ~/.config/wireplumber/wireplumber.conf.d/disable-device.conf:

monitor.alsa.rules = [
    {
        matches = [
            { node.description = "Device Name Here" }
        ]
        actions = {
            update-props = {
                node.disabled = true
            }
        }
    }
]

---

USB Troubleshooting

Diagnose USB Issues

lsusb -t                  # Show USB topology (buses, hubs, speeds)
lsusb                     # List USB devices with vendor:product IDs
sudo dmesg -w             # Watch kernel logs live

Known Issue: OBSBot Tiny 2 Lite + Rode NT-USB+ via Monitor Hub

When the camera starts streaming, the xHCI controller on the monitor hub chain floods with TRB errors, killing the mic’s audio stream. This is a Linux xHCI driver bug with the double-hub nesting (monitor hub → GenesysLogic sub-hub → Rode).

Fix: Connect the Rode directly to a PC USB port, not through the monitor hub.

Does NOT work: USB autosuspend disable, udev rules, WirePlumber rules. The issue is at the xHCI hardware/driver level.

---

Hyprland Window Rules

Caelestia uses the newer windowrule syntax with match: selectors (not windowrulev2).

# Disable transparency for specific apps
windowrule = opaque true, match:class obsidian
windowrule = opaque true, match:class google-chrome
 
# Float a window
windowrule = float true, match:class some-app
 
# Send to specific workspace
windowrule = workspace special:music, match:class Spotify
 
# Make games opaque + allow tearing
windowrule = opaque true, match:class steam_app_default
windowrule = immediate true, match:class steam_app_default

Find app class names with: hyprctl clients | grep class

---

Chrome Configuration

Chrome Flags (~/.config/chrome-flags.conf)

This file is auto-read by google-chrome-stable on launch.

--force-device-scale-factor=1.2

Other useful flags:

--enable-features=UseOzonePlatform
--ozone-platform=wayland

---

Obsidian

• Install natively with yay -S obsidian (not Flatpak) for CLI support and sharp Wayland rendering
• Flatpak Obsidian has blurry text on Wayland - fix with:

  flatpak override --user --env=ELECTRON_OZONE_PLATFORM_HINT=wayland md.obsidian.Obsidian

• Native install provides /usr/bin/obsidian CLI command

---

Mounting External Drives (Nautilus/GNOME)

If Nautilus says “not authorized” when mounting USB/HDD:

sudo pacman -S udisks2 polkit-gnome

Add to hypr-user.conf:

exec-once = /usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1

---

v4l2loopback (Virtual Camera)

Persist across reboots

# Install
sudo pacman -S v4l2loopback-dkms
 
# Auto-load module
echo "v4l2loopback" | sudo tee /etc/modules-load.d/v4l2loopback.conf
 
# Set parameters
echo 'options v4l2loopback video_nr=42 card_label="OBSBOT Virtual Camera" exclusive_caps=1' | sudo tee /etc/modprobe.d/v4l2loopback.conf
 
# Load now
sudo modprobe v4l2loopback video_nr=42 card_label="OBSBOT Virtual Camera" exclusive_caps=1

---

Flatpak Tips

• Flatpak apps aren’t available as terminal commands
• Fix blurry Electron apps on Wayland:

  flatpak override --user --env=ELECTRON_OZONE_PLATFORM_HINT=wayland <app.id>

• Prefer native yay installs over Flatpak for better integration
• Check Flatpak apps: flatpak list
• Run Flatpak: flatpak run com.example.App

---

Useful Packages

# Install from pacman
sudo pacman -S nautilus polkit-gnome udisks2 thunar v4l2loopback-dkms
 
# Install from AUR
yay -S google-chrome obsidian vscodium-bin obsbot-camera-control

---

Config File Locations

File	Location
Hyprland main config	~/.config/hypr/hyprland.conf (symlink)
Caelestia defaults	~/.local/share/caelestia/
Caelestia user overrides	~/.config/caelestia/
Foot terminal	~/.local/share/caelestia/foot/foot.ini
Starship prompt	~/.local/share/caelestia/starship.toml
Fish config	~/.config/caelestia/user-config.fish
PipeWire config	~/.config/pipewire/pipewire.conf.d/
WirePlumber config	~/.config/wireplumber/wireplumber.conf.d/
Shell UI config	~/.config/caelestia/shell.json
Chrome flags	~/.config/chrome-flags.conf