Scripts Reference

All scripts are installed to ~/.local/bin/ and should be in your PATH.

Theme & Appearance

theme-set theming essential

Switch the system-wide color theme across all applications

theme-set tokyo-night

bg-next theming

Cycle through wallpaper images for the current theme

bg-next

Super + B

nightlight-toggle theming

Toggle blue light filter for evening use

nightlight-toggle

Super + Shift + N

theme-set detailed usage

# Apply a theme
theme-set tokyo-night

# List available themes
theme-set --list
theme-set -l

# Show current theme
theme-set --current
theme-set -c

# Interactive picker (via fuzzel)
theme-set --select
theme-set -s
theme-set        # default action

Apps updated

Hyprland, Waybar, Foot, Ghostty, Mako, Fuzzel, Swaylock, GTK, Neovim, btop, VSCode/Cursor

Screenshots & Recording

screenshot utility

Capture screenshots using grim and slurp. Supports full screen, region, window, and smart (auto-detect active window) modes.

screenshot region

Shift + Print

Ctrl + Print

screenrecord utility

Record screen video with audio capture and GPU-accelerated encoding support

screenrecord

Super + Shift + Print

capture-menu utility

Interactive capture menu with all screenshot/recording options

capture-menu

magnifier utility

Desktop zoom via Hyprland cursor zoom

magnifier in

Super + ]

screenshot detailed usage

# Full screen
screenshot

# Select region interactively
screenshot region

# Active window
screenshot window

Screenshots saved to ~/Pictures/Screenshots/ with timestamp filenames.

Keybindings:

Print - Full screen
Shift + Print - Select region
Ctrl + Print - Active window

screenrecord detailed usage

# Start recording
screenrecord

# Stop recording (run again or press keybinding)
screenrecord stop

Recordings saved to ~/Videos/ in WebM format.

Audio & Display

volume utility

Control system audio volume

volume up

Media keys (XF86Audio*)

brightness utility

Control display brightness

brightness up

Brightness keys (XF86MonBrightness*)

osd-notify utility

Display on-screen notifications for volume/brightness changes. Called automatically by volume/brightness scripts.

osd-notify volume 75

volume detailed usage

volume up      # Increase 5%
volume down    # Decrease 5%
volume mute    # Toggle mute
volume get     # Show current level

brightness detailed usage

brightness up      # Increase 5%
brightness down    # Decrease 5%
brightness get     # Show current level
brightness set 50  # Set to 50%

System Controls

toggle-idle utility

Toggle idle behavior (screen lock, display off, suspend). Useful when watching videos or presenting.

toggle-idle

system-menu utility essential

Interactive system control menu. Options: Lock, Logout, Suspend, Reboot, Shutdown.

system-menu

Super + Escape

battery-status utility

Show battery information (for laptops). Output: percentage, charging status, time remaining.

battery-status

screen-toggle utility phone

Toggle the active Wayland display power. Uses Sway output power or Hyprland DPMS.

screen-toggle toggle

phone-screen-setup utility phone

Install the PinePhone Pro Sway power-button binding for screen-toggle.

phone-screen-setup

XF86PowerOff

phone-sensors utility phone

Read PinePhone Pro proximity/light and accelerometer/gyro sysctls.

phone-sensors status

phone-led utility phone

Control the PinePhone Pro RGB notification LED through a narrow root helper.

phone-led notify blue 2

phone-proximity-monitor utility phone

Opt-in proximity policy for turning the Wayland display off/on.

phone-proximity-monitor dry-run

wifi-manager utility

Interactive WiFi manager for native wlan* and wifibox0

wifi-manager

phone screen power detailed usage

screen-toggle off      # Turn the active display off
screen-toggle on       # Turn the active display on
screen-toggle toggle   # Toggle active display power
screen-toggle status   # Print on/off state when supported

# Install a managed Sway config block:
# bindsym --release XF86PowerOff exec ~/.local/bin/screen-toggle toggle
phone-screen-setup

On the PinePhone Pro, libinput reports the side power key as KEY_POWER (116). Sway receives it through XKB as XF86PowerOff, so the installer binds that keysym instead of a raw evdev code.

phone sensors and LED detailed usage

phone-sensors status       # Human-readable sensor values
phone-sensors json         # Machine-readable raw values
phone-sensors near         # 0/1 proximity state
phone-sensors watch 1      # Poll once per second

phone-led status
phone-led blue
phone-led notify amber 2
phone-led off

phone-proximity-monitor status
phone-proximity-monitor dry-run 10
phone-proximity-monitor run

start-lisgd-sway           # Restart PinePhone Sway touch gestures

phone-proximity-monitor is intentionally opt-in. It will not be autostarted until the STK3311 thresholds are tuned against real use.

wifi-manager detailed usage

wifi-manager         # Show menu
wifi-manager select  # Choose network
wifi-manager status  # Connection status
wifi-manager saved   # List saved networks
wifi-manager disconnect

Window Management

window-transparency utility

Adjust window transparency

window-transparency 0.9

hyprland-session utility

Session management for Hyprland

hyprland-session

hyprland-square-toggle utility

Toggle window to 1:1 square aspect ratio

hyprland-square-toggle

Super + Ctrl + Shift + S

hyprland-plugins utility

Manage Hyprland plugins (hyprscrolling, hyprexpo, etc)

hyprland-plugins menu

window-transparency detailed usage

window-transparency 0.9    # 90% opacity
window-transparency 1.0    # Fully opaque

Terminal Layouts

tdl utility

Tmux dev layout: nvim left, terminal right

tdl myproject

tdlm utility

Tmux dev layout (main): nvim + terminal + server

tdlm myproject

tsl utility

Tmux swarm layout: 4 equal panes

tsl workers

Quick Text

quick-type utility

Type text snippets via wtype

quick-type name

Super + Ctrl + 1/2

Accessibility

accessibility-keys accessibility

Toggle sticky/slow/bounce keys

accessibility-keys menu

autologin-toggle system

Toggle ly display manager autologin

autologin-toggle

AI

omfreebdy-ai-skill ai

Ask the local LLM about system customization

omfreebdy-ai-skill “make font bigger”

Launchers & Menus

omfreebdy-menu utility essential

Main system menu with hierarchical submenus

omfreebdy-menu

Super + D

keybindings-show utility

Display all configured keybindings

keybindings-show

Super + F1

emoji-picker utility

Search and insert emoji characters

emoji-picker

start-waybar utility

Start or restart the Waybar status bar

start-waybar

omfreebdy-menu submenus

Submenus:

Apps - Launch applications
Capture - Screenshot/recording options, Zoom In/Out/Reset, Smart Screenshot
Help - Keybindings, About, AI Skill
Install - App installers, AI Tools (Claude Code, OpenCode, Pi Agent Harness)
Setup - Accessibility, Autologin, WiFi, Bluetooth, Audio, Display
Style - Theme and background selection
System - Power and session controls, Hyprland Plugins
Settings - WiFi, Bluetooth, Audio, Display

Hardware & System

usb-mount utility

Auto-mount and manage USB drives. Called by devd on attach/detach, or use interactively.

usb-mount list

audio-switch utility

Switch the default OSS audio output device interactively.

audio-switch

power-profile utility

Switch CPU power profile. Controls powerd and frequency scaling.

power-profile select

hibernate utility

Suspend-to-disk via ACPI S4. Checks for S4 support and sufficient swap before proceeding.

hibernate

disk-health utility

SMART disk health status for all detected drives.

disk-health status

printer-setup utility

CUPS printer management — list printers, check status, open web admin.

printer-setup status

usb-mount detailed usage

usb-mount list        # List mounted USB drives
usb-mount mount       # Interactive mount picker
usb-mount unmount     # Interactive unmount picker
usb-mount eject       # Unmount and eject safely
usb-mount auto-attach # Called by devd on plug-in
usb-mount auto-detach # Called by devd on removal

Drives are mounted under /media/ with labels from glabel or volume names.

power-profile detailed usage

power-profile performance   # Max CPU frequency, no throttling
power-profile balanced      # powerd adaptive (default)
power-profile powersave     # Min frequency, aggressive throttling
power-profile status        # Show current profile
power-profile select        # Interactive picker via dmenu-pick

disk-health detailed usage

disk-health status          # Quick health summary for all disks
disk-health check /dev/ada0 # Full SMART report for one disk
disk-health all             # Detailed report for all disks

Requires smartmontools: sudo pkg install smartmontools

printer-setup detailed usage

printer-setup status   # Show CUPS status and installed printers
printer-setup list     # List all configured printers
printer-setup web      # Open CUPS web admin (http://localhost:631)
printer-setup add      # Add a printer via lpadmin
printer-setup test     # Print a test page

Networking

network-discover utility

Browse LAN services via Avahi/mDNS. Scans for 5 seconds and shows an interactive picker.

network-discover

vpn-setup utility

Install and configure WireGuard or Tailscale VPN.

vpn-setup status

firewall utility

PF firewall management — check status, allow or deny ports.

firewall status

file-share utility

Send or receive files over LAN. Uses LocalSend if available, falls back to Python HTTP.

file-share send photo.jpg

vpn-setup detailed usage

vpn-setup status                      # Show WireGuard + Tailscale status
vpn-setup wireguard install           # Install wireguard-tools and kmod
vpn-setup wireguard up wg0            # Bring up wg0 tunnel
vpn-setup wireguard down wg0          # Tear down wg0 tunnel
vpn-setup tailscale install           # Install Tailscale (Linux jail)
vpn-setup tailscale up                # Connect to Tailscale network
vpn-setup tailscale down              # Disconnect from Tailscale

firewall detailed usage

firewall status                # Show PF state and active rules
firewall allow 8080            # Allow TCP port 8080
firewall allow 53 udp          # Allow UDP port 53
firewall deny 22               # Block port 22
firewall list                  # List current rules
firewall reset                 # Reload /etc/pf.conf

file-share detailed usage

file-share send photo.jpg      # Share a file (shows URL or uses LocalSend)
file-share receive             # Start receiving mode
file-share install             # Install LocalSend

Internationalization

locale-set utility

Set system locale and keyboard layout.

locale-set select

input-method-setup utility

Install and configure fcitx5 for CJK and international input.

input-method-setup install

tz-auto utility

Auto-detect timezone from IP geolocation via worldtimeapi.org.

tz-auto —apply

locale-set detailed usage

locale-set status              # Show current locale and keyboard
locale-set select              # Interactive picker
locale-set set en_US.UTF-8     # Set locale directly
locale-set keyboard us         # Set keyboard layout
locale-set keyboard jp         # Japanese layout

input-method-setup detailed usage

input-method-setup status      # Check if fcitx5 is installed and running
input-method-setup install     # Install fcitx5 and a CJK engine
input-method-setup enable      # Add fcitx5 to session autostart
input-method-setup disable     # Remove from autostart

Supports Japanese (mozc), Chinese (rime, libpinyin), Korean (hangul), and more via fcitx5 add-ons.

tz-auto detailed usage

tz-auto              # Detect and print recommended timezone (no change)
tz-auto --apply      # Detect and apply the timezone

Uses worldtimeapi.org/api/ip — no API key required.

omfreebdy Management

omfreebdy-setup essential utility

First-run setup wizard. Runs automatically on first login; re-run with —force.

omfreebdy-setup —force

omfreebdy-channel utility

Switch the update channel (git branch) between stable and dev.

omfreebdy-channel stable

omfreebdy-migrate utility

Apply pending config migrations after an upgrade.

omfreebdy-migrate run

omfreebdy-about utility

Show omfreebdy version, active session, theme, and system summary.

omfreebdy-about

dmenu-pick utility

Universal picker used by all interactive scripts. Auto-selects fuzzel (Wayland), rofi (X11), or fzf (terminal).

echo -e “a\nb\nc” | dmenu-pick —prompt “Choose: ”

omfreebdy-channel detailed usage

omfreebdy-channel status    # Show current channel, remote, last update
omfreebdy-channel stable    # Switch to stable branch
omfreebdy-channel dev       # Switch to dev branch

After switching channels, run mise run update to pull and apply changes.

omfreebdy-migrate detailed usage

omfreebdy-migrate list      # Show all migrations and their status
omfreebdy-migrate status    # Show pending migrations
omfreebdy-migrate run       # Apply all pending migrations

Migrations are numbered shell scripts in the migrations/ directory. Each runs once and is tracked in ~/.config/omfreebdy/migration-version.

dmenu-pick detailed usage

# Pipe options into dmenu-pick
printf "Option A\nOption B\nOption C" | dmenu-pick --prompt "Choose: "

# Control width and height
printf "a\nb" | dmenu-pick --prompt "Pick: " --width 40 --lines 5

# Password mode (hidden input)
dmenu-pick --password --prompt "Password: "

Used internally by wifi-manager, theme-set, audio-switch, network-discover, and many other scripts.

Adding Custom Scripts

Custom Script Requirements

Make sure your scripts are executable and located in ~/.local/bin/ which should be in your PATH.

Create your script

Add a new file in ~/.local/bin/:

#!/bin/sh
# ~/.local/bin/my-script
echo "Hello, omfreebdy!"

Make it executable

chmod +x ~/.local/bin/my-script

Bind to a key (optional)

Add a binding in ~/.config/hypr/conf/bindings.conf:

bind = SUPER, M, exec, my-script