SirBlob/dotfiles
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add the installer, uninstaller, and generated docs

Browse Source
This commit is contained in:
SirBlob committed 2026-09-20 00:19:38 -04:00
1 parent 0c422e7345
commit 3e65d176e3
100 files changed
+2585
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/commands.md
+559
View File
@@ -0,0 +1,559 @@
# Commands
Generated by `blob-docs-commands` from the `# blob:summary=` line in each
file. Do not edit by hand.
Commands marked hidden are plumbing other commands call, and are left out
of the `blob` listing.
## audio
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-audio-availability` | Print PulseAudio sink availability for the shell | - |
| `blob-audio-input-mute` | Toggle microphone mute. Drives the hardware mic-mute LED on laptops that expose one. | - |
| `blob-audio-input-set` | Set the default audio input and move active streams | <node-id> <source-name> |
| `blob-audio-restart` | Restart audio services and recover stuck USB audio devices. | - |
| `blob-audio-sink` | Print the sink whose volume and mute a given output really uses | [sink-name] |
| `blob-audio-sink-set` | Set the default audio output and move active streams | <node-id> <sink-name> |
| `blob-audio-sink-switch` | Switch between audio outputs while preserving the mute status | - |
| `blob-audio-source-switch` | Cycle to the next media source and transfer playback when the current source is playing | [next\|previous] |
| `blob-audio-tuning` | Manage the speaker tuning for this laptop | <on\|off\|status\|match\|fronted-sink> [--force] |
| `blob-audio-volume` | Adjust output volume and show the Blob OSD | <raise\|lower\|mute-toggle\|+N\|-N> |
## bar
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-bar` | Configure the bar and its widget layout | use <id> \| reset \| defaults \| position <top\|bottom\|left\|right> \| transparent <true\|false\|toggle> \| put <id> [placement] \| move <id> [placement] \| set <id> <key> <value> [--json] [placement] |
| `blob-bar-color` | Choose a legible transparent bar text color (hidden) | - |
## battery
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-battery-low` | Send the low battery warning notification and run battery-low hooks. (hidden) | <percentage> |
| `blob-battery-status` | Returns a formatted battery status string with percentage and power draw/charge. | [--shell] |
## bg
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-bg-cache` | Cache background switcher thumbnails for the current theme | - |
| `blob-bg-current` | Show current background | - |
| `blob-bg-install` | Open the current theme's user background folder | - |
| `blob-bg-next` | Cycle to the next background for the current theme | - |
| `blob-bg-set` | Set the current background image | <path-to-image> |
| `blob-bg-switcher` | Open the Blob background switcher | - |
## bluetooth
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-bluetooth-device` | Control a Bluetooth device | [pair\|connect\|disconnect\|forget] <address> |
| `blob-bluetooth-power` | Turn Bluetooth on or off, remembered across reboots | <on\|off\|toggle\|is-on> |
| `blob-bluetooth-restart` | Unblock and restart the bluetooth service. | - |
## boot
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-boot` | - | - |
## branding
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-branding-about` | Edit, set, or reset About branding | <image\|text\|reset> |
| `blob-branding-screensaver` | Edit, set, or reset screensaver branding | <image\|text\|reset> |
## brightness
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-brightness-ddc` | Show or adjust DDC/CI display brightness for a Hyprland monitor. | <monitor> [+N%\|N%-\|N%] |
| `blob-brightness-display` | Show or adjust brightness on the focused display. | [--no-osd] [--monitor name] [+N%\|N%-\|N%\|off\|on] |
| `blob-brightness-display-apple` | Show or adjust Apple Studio Display and Apple XDR Display brightness using asdcontrol. | [--no-osd] [+N%\|N%-\|N%] |
| `blob-brightness-keyboard` | Adjust keyboard backlight brightness using available steps. | [--no-osd] <up\|down\|cycle\|off\|restore> |
| `blob-brightness-keyboard-mute` | Set the mic-mute indicator LED on laptops that expose a platform::micmute LED node. | <on\|off> |
## capture
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-capture-qr` | Decode a QR code from a screenshot region | - |
| `blob-capture-record` | Start or stop screen recording | [--fullscreen] [--with-desktop-audio] [--with-microphone-audio] [--with-webcam] [--webcam-device=<device>] [--webcam-size=<small\|medium\|large>] [--resolution=<size>] [--stop-recording] |
| `blob-capture-record-webcam` | Pick a webcam and start a screen recording with it | - |
| `blob-capture-region` | Pick a screen region over frozen screen content (hidden) | [region\|windows\|smart\|fullscreen] [--keep-freeze] [--match-monitor] \| --take-fullscreen \| --take-window \| --select-window <next\|prev\|left\|right\|up\|down> |
| `blob-capture-screenshot` | Take a screenshot | [smart\|region\|windows\|fullscreen] [slurp\|copy\|save] [--editor=<name>] |
| `blob-capture-text` | Extract text from a screenshot region with OCR | - |
| `blob-capture-webcam-list` | List webcam devices that support video capture (hidden) | - |
| `blob-capture-webcam-resize` | Resize the active webcam recording overlay | <smaller\|larger\|reset\|small\|medium\|large> |
## clipboard
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-clipboard-file` | Copy a file to the clipboard and paste it (hidden) | [--copy-only] <mime-type> <path> |
| `blob-clipboard-open` | Open a clipboard history entry (hidden) | --history-index <index> |
| `blob-clipboard-text` | Copy text to the clipboard and type or paste it (hidden) | [--shift-insert] [--copy-only] [--history-index <index>\|<text>] |
## cmd
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-cmd-cwd` | Print the current working directory of the active terminal window (hidden) | - |
| `blob-cmd-missing` | Check whether any required commands are missing | - |
| `blob-cmd-present` | Check whether all required commands are available | - |
## crash
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-crash-watch` | Watch for process crashes and offer an AI diagnosis (hidden) | - |
## default
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-default-browser` | Set the default browser for Blob and XDG handlers | [chromium\|chrome\|brave\|brave-origin\|edge\|firefox\|zen] |
| `blob-default-editor` | Set the default editor used by blob-launch-editor | [code\|cursor\|zed\|sublime_text\|helix\|vim\|emacs\|nvim] |
| `blob-default-terminal` | Set the default terminal used by xdg-terminal-exec | [alacritty\|foot\|ghostty\|kitty] |
## disk
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-disk-speedtest` | Measure live disk read and write speed | [target-dir] |
## display
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-display-size` | Scale text everywhere — blob shell, GTK apps, and terminals | [size\|reset] |
| `blob-display-state` | Print monitor panel state for the shell | - |
## docs
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-docs-commands` | Regenerate docs/commands.md from each command's own metadata (hidden) | - |
| `blob-docs-keybinds` | Regenerate docs/keybinds.md from the Hyprland Lua bindings (hidden) | - |
## drive
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-drive-info` | Print drive information such as size, model, and mount details | <drive> |
| `blob-drive-password` | Set a new encryption password for a drive selected. | - |
| `blob-drive-select` | Select a drive from a list with info that includes space and brand. Used by blob-drive-password. | - |
## file
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-file-select` | Pick files with the desktop file chooser | [--title <title>] [--multiple] [--directory] [--extensions "<ext ext...>"] |
## font
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-font-current` | Show current monospace font | - |
| `blob-font-list` | List available monospace fonts | - |
| `blob-font-set` | Set the system monospace font | <font-name> |
## git
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-git-url-check` | Check that a git URL names a repository, not a transport helper (hidden) | <git-url> |
## hibernation
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-hibernation-available` | Check if hibernation is supported | - |
## hook
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-hook` | Run a named hook from ~/.config/blob/hooks/<name> and ~/.config/blob/hooks/<name>.d/. | [name] [args...] |
## hw
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-hw-clamshell` | Returns true when clamshell mode is active (hidden) | - |
| `blob-hw-dell-xps-haptic-touchpad` | Match Dell XPS systems with the Synaptics haptic touchpad. | - |
| `blob-hw-display` | Print the most likely display backlight device. | - |
| `blob-hw-external` | Returns true when an external monitor is physically connected. | - |
| `blob-hw-fingerprint` | Returns true when a fingerprint reader is present (hidden) | - |
| `blob-hw-hybrid-gpu` | Detect whether the system has an active hybrid GPU configuration | - |
| `blob-hw-laptop` | Returns true when running on a laptop (has a lid or laptop chassis). | - |
| `blob-hw-laptop-closed` | Returns true when the laptop lid is closed (hidden) | - |
| `blob-hw-match` | Match against the computer's DMI product name or product family (case-insensitive). | <pattern> |
| `blob-hw-nvidia` | Detect whether the computer has an NVIDIA GPU. | - |
| `blob-hw-nvidia-gsp` | Detect whether the computer has an NVIDIA GPU with GSP firmware (Turing or newer). | - |
| `blob-hw-nvidia-without-gsp` | Detect whether the computer has an NVIDIA GPU without GSP firmware (Maxwell/Pascal/Volta). | - |
| `blob-hw-touchpad` | Print the detected Hyprland touchpad or trackpad device name | - |
| `blob-hw-touchscreen` | Print the detected Hyprland touchscreen or tablet device name | - |
| `blob-hw-webcam` | Check whether a webcam is available | - |
## hypr
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-hypr-focus` | Focus a Hyprland window by application identity | <app-name> |
| `blob-hypr-monitor-clamshell` | Apply clamshell display state to Hyprland monitors (hidden) | - |
| `blob-hypr-monitor-external` | Returns true when Hyprland has an active external monitor (hidden) | - |
| `blob-hypr-monitor-focused` | Print the name of the currently focused Hyprland monitor. | - |
| `blob-hypr-monitor-focused-apple` | Return success if the focused or named Hyprland monitor is an Apple display. | [monitor] |
| `blob-hypr-monitor-internal` | Enable, disable, toggle, or recover the internal laptop display | <on\|off\|toggle\|recover> |
| `blob-hypr-monitor-laptop` | Print the name of the built-in laptop display, including disabled outputs. | - |
| `blob-hypr-monitor-mirror` | Enable, disable, toggle, or recover mirroring the internal display to an external monitor | <on\|off\|toggle\|recover> |
| `blob-hypr-monitor-modeless` | Returns true when Hyprland has an enabled monitor with no mode (hidden) | - |
| `blob-hypr-monitor-scaling` | Show, set, or adjust focused Hyprland monitor scaling | [up\|down\|SCALE] |
| `blob-hypr-monitor-watch` | Watch Hyprland monitor events and recover monitor toggles when a monitor is removed | - |
| `blob-hypr-reload-guard` | Pause or resume Hyprland config auto-reload around package transactions. (hidden) | - |
| `blob-hypr-restart` | Reload hyprland configuration (used by the Blob theme switching). | - |
| `blob-hypr-session-locked` | Returns true when the compositor holds a session lock (hidden) | - |
| `blob-hypr-toggle` | Toggle permanent Hyprland flags by copying them into a directory that's sourced entirely. | <flag-name> [on\|off\|toggle] |
| `blob-hypr-toggle-disabled` | Check if a Hyprland toggle is currently disabled (missing). | <flag-name> |
| `blob-hypr-toggle-enabled` | Check if a Hyprland toggle is currently enabled. | <flag-name> |
| `blob-hypr-window-close-all` | Close all open windows | - |
| `blob-hypr-window-gaps-toggle` | Toggles the window gaps globally between no gaps and the default. | - |
| `blob-hypr-window-pop` | Toggle to pop-out a tile to stay fixed on a display basis. | [width height x y] |
| `blob-hypr-window-single-square-aspect-toggle` | Toggle single-window square aspect ratio. | - |
| `blob-hypr-window-tiled-fullscreen-toggle` | Toggle tiled fullscreen for the focused Hyprland window | - |
| `blob-hypr-window-transparency-toggle` | Toggles transparency for the currently focused window. | - |
| `blob-hypr-window-width` | Save or restore the focused Hyprland window width | <save\|restore> |
| `blob-hypr-workspace-layout-toggle` | Toggle the layout on the current active workspace between dwindle and scrolling | - |
## install
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-install-font` | Install a Nerd Font package and switch the system to it | <display-name> <package> <family> |
| `blob-install-launch` | Install a packaged app and launch it once it finishes | <display-name> <packages> <desktop-id> |
## launch
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-launch-about` | Launch the fastfetch TUI that gives information about the current system. | - |
| `blob-launch-browser` | Launch the default browser as determined by xdg-settings. | [url] |
| `blob-launch-config-editor` | Open a config file in the user's editor and surface a toast | <path> |
| `blob-launch-docker-tui` | Open the Docker TUI (lazydocker) with access to the Docker daemon (hidden) | - |
| `blob-launch-editor` | Launch the default editor selected via Blob defaults. | [--inline] <path> |
## launcher
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-launcher-remove` | Remove or uninstall the selected launcher entry (hidden) | <desktop-id> <name> |
## launch
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-launch-floating` | Launch a floating terminal with the Blob presentation wrapper | <command> |
| `blob-launch-or-focus` | Launch an app or focus an existing window matching a pattern | <window-pattern> <launch-command> |
| `blob-launch-or-focus-tui` | Launch a TUI or focus an existing terminal window for it | [--app-id=<app-id>] <command> [args...] |
| `blob-launch-screensaver` | Launch the Blob screensaver in the default terminal on the system with the correct font configuration. | - |
| `blob-launch-shell` | Launch the Blob shell with its log kept in the journal (hidden) | - |
| `blob-launch-tui` | Launch a TUI command in the default terminal with Blob styling | [--app-id=<app-id>] <command> [args...] |
## menu
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-menu` | Control the Blob menu (toggle / summon / close / refresh) | [toggle\|summon\|close\|refresh\|ping] [route] |
| `blob-menu-emoji` | Launch emojis | - |
| `blob-menu-emoji-insert` | Insert an emoji into the focused application (hidden) | <emoji> |
| `blob-menu-file` | Pick a file from a menu | label paths formats [menu args...] |
| `blob-menu-images` | Open a generic image selector menu | [--selected <image>] [--print-name] [--show-labels] [--filterable] [--lazy-thumbnails] [--preload] [--cache-only] <image-dir>... |
| `blob-menu-keybindings` | Display Hyprland keybindings defined in your configuration using an interactive search menu. | - |
| `blob-menu-plugin` | Pick a shell plugin to enable, disable, clone, or remove | <enable\|disable\|clone\|remove> |
| `blob-menu-select` | Pick one option from a menu | prompt [option...] [-- menu args...] |
| `blob-menu-share` | Share clipboard, files, or folders with LocalSend | <clipboard\|file\|folder> [path...] |
| `blob-menu-timezone` | Select and set the system timezone | - |
## network
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-network-band` | Show or pin the Wi-Fi band for the active connection | [auto\|2.4\|5\|6] |
| `blob-network-dns` | Show or configure the system DNS provider | [Cloudflare\|Google\|DHCP\|Custom] |
| `blob-network-iwd` | - | - |
| `blob-network-password` | Print the active Wi-Fi connection's password | <interface> |
| `blob-network-qr` | Generate a Wi-Fi QR matrix for the shell | [--meta] [interface] |
| `blob-network-restart` | Unblock and restart the Wi-Fi service. | - |
| `blob-network-speedtest` | Measure live internet speed for one direction | [down\|up] |
| `blob-network-status` | Print active network status for the shell | [--verbose] |
## notification
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-notification-battery` | Show the current battery status notification | - |
| `blob-notification-time` | Show the current time and date notification | - |
| `blob-notification-wait` | Wait for the desktop notification server to accept notifications (hidden) | [timeout-seconds] |
| `blob-notification-weather` | Toggle the current weather panel | - |
## notify
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-notify-dismiss` | Dismiss a notification by summary substring. Used by the first-run notifications to dismiss them after clicking for action. | <summary> |
| `blob-notify-send` | Send an Blob desktop notification | [--app-name <app-name>] [-g <glyph>] [-u <low\|normal\|critical>] [-i <icon>] [-t <ms>] [-r <id>] [-p] [--image <path-or-uri>] <headline> [description] [--exec <program> [args...]] |
## osd
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-osd` | Show the Blob Quickshell on-screen display | [-i\|--icon <icon>] [-m\|--message <text>] [-p\|--progress <0-100>] [-d\|--duration <ms>] |
## pkg
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-pkg-add` | Install Arch packages if they are missing | <packages...> |
| `blob-pkg-aur` | Returns true if the AUR is up and available. | - |
| `blob-pkg-aur-install` | Show a fuzzy-finder TUI for picking new AUR packages to install. | - |
| `blob-pkg-drop` | Remove all the named packages from the system if they're installed (otherwise ignore). | <packages...> |
| `blob-pkg-install` | Show a fuzzy-finder TUI for picking new Arch and OPR packages to install. | - |
| `blob-pkg-missing` | Returns true if any of the named packages are missing from the system (or false if they're all there). | <packages...> |
| `blob-pkg-present` | Returns true if all of the named packages are installed on the system (or false if any of them are missing). | <packages...> |
| `blob-pkg-remove` | Show a fuzzy-finder TUI for picking packages installed on the system to be removed. | - |
## plugin
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-plugin-add` | Add a shell plugin from git | [git-url] [--enable] [--yes] |
| `blob-plugin-catalog` | Emit every first-party and user plugin manifest as JSON (hidden) | - |
| `blob-plugin-clone` | Clone a built-in Blob shell plugin into your own config | <source-id> [--edit] |
| `blob-plugin-enable` | Enable a shell plugin | <id> [placement] |
| `blob-plugin-list` | List discovered shell plugins | [--json] |
| `blob-plugin-remove` | Remove an installed shell plugin | [id] [--yes] |
| `blob-plugin-validate` | Validate a plugin folder against the Blob plugin manifest schema | <plugin-folder> |
## plymouth
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-plymouth-set` | Set the Plymouth boot theme colors and logo | <background-hex> <text-hex> <path-to-logo.png> |
## power
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-power-list` | Returns a list of all the available power profiles on the system. | [--active-state] |
## powerprofiles
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-powerprofiles-init` | Set the correct power profile on boot based on current AC/battery state. | - |
## power
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-power-set` | Set and remember the power profile for AC or battery use | [autodetect\|ac\|battery] [power-saver\|balanced\|performance] |
## refresh
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-refresh-config` | Copy a shipped user config from $BLOB_PATH/config into ~/.config (backs up your version). | <config-path> |
| `blob-refresh-hyprland` | Overwrite all the user Hyprland Lua configs in ~/.config/hypr with the Blob defaults. | - |
| `blob-refresh-hyprsunset` | Overwrite the user config for hyprsunset with the Blob default and restart the service. | - |
| `blob-refresh-plymouth` | Overwrite the user config for the Plymouth drive decryption and boot sequence with the Blob default and rebuild it. | - |
| `blob-refresh-shell` | Reset shell.json to Blob defaults | - |
## reminder
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-reminder` | Set and show lightweight desktop notification reminders | [-i\|--interactive] \| <minutes> [message] \| show [-j\|--json] \| clear |
## remove
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-remove-security-fido2` | Remove FIDO2 authentication from sudo and polkit | - |
| `blob-remove-security-sudoless-docker` | Disable sudoless Docker by removing your user from the docker group | - |
## restart
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-restart-app` | Restart an application by killing it and relaunching via uwsm. | <application-name> [application-args...] |
| `blob-restart-btop` | Reload btop configuration (used by the Blob theme switching). | - |
| `blob-restart-gum` | Export the current theme's gum styling into the environment (hidden) | - |
| `blob-restart-hyprsunset` | Restart the hyprsunset service (used for blue light filtering/night light). | - |
| `blob-restart-terminal` | Reload supported terminal emulators after config changes | - |
| `blob-restart-trackpad` | Reset the trackpad by unbinding and rebinding its driver. | - |
| `blob-restart-xcompose` | Restart the XCompose input method service (fcitx5) to apply new compose key settings. | - |
## screensaver
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-screensaver` | Run the Blob screensaver using random effects from TTE. | - |
## secret
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-secret` | - | - |
## setup
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-setup-direct-boot` | Add or remove an EFI boot entry for the Blob UKI, allowing the system to boot directly | - |
| `blob-setup-security-fido2` | Set up FIDO2 authentication for sudo and polkit | - |
| `blob-setup-security-fingerprint` | Set up fingerprint authentication for sudo, polkit, and lock screen | - |
| `blob-setup-security-sshd` | Set up the OpenSSH server, open the firewall, and authorize an SSH key | [--key=<public-key>] |
| `blob-setup-security-sudoless-docker` | Enable sudoless Docker by adding your user to the docker group (root-equivalent!) | - |
## shell
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-shell` | Send an IPC call to the running Blob shell | [-q] <target> <method> [args...] |
| `blob-shell-config` | Shared helpers for editing ~/.config/blob/shell.json (source this, don't run it). (hidden) | - |
| `blob-shell-restart` | Restart the Blob shell | - |
## show
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-show-done` | Display a "Done!" message and wait for user to press any key. | - |
| `blob-show-logo` | Display the Blob logo in the terminal using green color. | - |
## state
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-state` | Manage persistent state files for Blob toggles and settings. (hidden) | <set\|clear> <state-name-or-pattern> |
## sudo
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-sudo-docker` | Succeed when Docker needs sudo, fail when it can be used directly (hidden) | [--configured] |
| `blob-sudo-keepalive` | Prompt for sudo once and keep the credential alive in the background. | - |
| `blob-sudo-passwordless` | Toggle passwordless sudo for the current user. | [MINUTES] |
## system
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-system-lid` | Lock and reconcile displays when the laptop lid closes (hidden) | - |
| `blob-system-lock` | Lock the computer and turn off the display | - |
| `blob-system-logout` | Log out after closing application windows | - |
| `blob-system-reboot` | Reboot after closing application windows | - |
| `blob-system-shutdown` | Shut down after closing application windows | - |
| `blob-system-sleep` | Lock before suspend and wait for the session lock to become secure (hidden) | - |
| `blob-system-sleep-monitor` | Monitor sleep preparation and lock before suspend (hidden) | - |
| `blob-system-stats` | Print CPU and memory stats for the shell | [--bar-widget] |
| `blob-system-wake` | Wake displays and restore brightness after idle | - |
## tablet
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-tablet-follow` | - | - |
## theme
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-theme-browser` | Apply the current theme color to Chromium, Chrome, Edge, and Brave (hidden) | - |
| `blob-theme-browser-policy` | Write the current theme color into the browser policy directories (hidden) | <rrggbb> |
| `blob-theme-color` | Resolve semantic colors from an Blob theme colors.toml (hidden) | [--file <colors.toml>] (--all \| --raw \| <key> [fallback]) |
| `blob-theme-contrast` | - | - |
| `blob-theme-current` | Show current theme | - |
| `blob-theme-dir` | Print the directory holding a theme, preferring a user-installed copy | <theme-name> |
| `blob-theme-dynamic` | Apply the pywal-generated theme built from the current wallpaper | - |
| `blob-theme-extras` | List the user-installed themes that came from a git clone | - |
| `blob-theme-foot` | Apply current Blob theme colors to running Foot terminals (hidden) | - |
| `blob-theme-import` | Generate a theme's colors.toml from its alacritty.toml palette (hidden) | <theme-dir> |
| `blob-theme-install` | Install a theme from a git repository | [git-repo-url] |
| `blob-theme-list` | List available themes | - |
| `blob-theme-menu` | Pick a color theme from the local and bundled sets | [--mode\|--print] |
| `blob-theme-osc` | Print OSC sequences for an Blob color theme (hidden) | - |
| `blob-theme-refresh` | Refresh the current theme from its templates. | - |
| `blob-theme-remove` | Remove a user-installed theme | [theme-name] |
| `blob-theme-set` | Apply an Blob theme | <theme-name> |
| `blob-theme-share` | Fetch a shared theme by link or id and apply it as blob-dynamic | <share-link-or-id> |
| `blob-theme-switcher` | Open the Blob theme switcher | - |
| `blob-theme-templates` | Generate themed config files from Blob templates (hidden) | - |
| `blob-theme-update` | Update user-installed git themes | - |
## toggle
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-toggle` | Toggle Blob features between enabled and disabled | <flag-name> [toggle\|on\|off] |
| `blob-toggle-bar` | Toggle bar visibility without killing the Blob shell | [toggle\|on\|off] |
| `blob-toggle-crash-capture` | Toggle crash capture notifications | - |
| `blob-toggle-enabled` | Check if a toggle is enabled (flag file exists) | <flag-name> |
| `blob-toggle-glass` | - | - |
| `blob-toggle-hybrid-gpu` | Toggle dedicated vs integrated GPU mode via supergfxd (for hybrid gpu laptops, like Asus G14). | - |
| `blob-toggle-idle` | Toggle idle behavior so the system either idles normally or stays awake | [toggle\|stay-awake\|allow-idle\|status] |
| `blob-toggle-input` | Enable, disable, or toggle a Hyprland input device (hidden) | <touchpad\|touchscreen> [on\|off\|toggle] |
| `blob-toggle-nightlight` | Toggle nightlight screen temperature | [--status] |
| `blob-toggle-screensaver` | Toggle screensaver availability | - |
| `blob-toggle-silencing` | Toggle notification do-not-disturb mode | - |
| `blob-toggle-tablet` | - | - |
| `blob-toggle-touchpad` | Enable, disable, or toggle the touchpad | [on\|off\|toggle] |
| `blob-toggle-touchscreen` | Enable, disable, or toggle the touch functionality of the screen | [on\|off\|toggle] |
## transcode
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-transcode` | Transcode pictures and videos for sharing | [--path path] [input] [format] [resolution] |
| `blob-transcode-ascii` | Transcode an image into ASCII/Unicode art text | <input-image.svg\|png> <output-path> [--width <columns>] [--height <rows>] [--mode <braille\|block>] [--threshold <percent>] [--invert] |
## tui
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-tui-install` | Create a desktop launcher for a terminal UI app | [name command window-style icon-url-or-name] |
| `blob-tui-remove` | Remove a terminal UI desktop launcher | [name] |
| `blob-tui-remove-all` | Remove all TUIs installed via blob-tui-install. | - |
## update
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-update` | Update system and AUR packages | [--no-confirm] |
| `blob-update-available` | Print the number of pending package updates (hidden) | - |
| `blob-update-firmware` | Update system firmware using fwupd. Ensures the fwupd EFI binary is installed | - |
| `blob-update-time` | Restart system time synchronization | - |
## wallpaper
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-wallpaper-set` | Set a wallpaper from ~/wallpapers and recolor the desktop from it | [--menu\|<file>] |
## weather
| Command | Does | Arguments |
| --- | --- | --- |
| `blob-weather-card` | Print a one-line weather summary for the quick settings card (hidden) | - |
| `blob-weather-icon` | Returns a weather condition icon, adjusted for live sunrise and sunset. | - |
| `blob-weather-location` | Show or set the location used for weather reports | - |
| `blob-weather-status` | Returns a formatted weather status string with temperature and wind speed. | - |
## Totals
252 commands.
docs/keybinds.md
+202
View File
@@ -0,0 +1,202 @@
# Keybindings
Generated by `blob-docs-keybinds` from the `o.bind` calls in the Hyprland
Lua files. Do not edit by hand.
Personal overrides in `hypr/bindings.lua` win over the defaults, and
`hl.unbind` in that file removes a default outright.
## Personal
| Keys | Action |
| --- | --- |
| `SUPER + ALT + SPACE` | Blob menu |
| `SUPER + ALT + W` | Wallpaper picker |
| `SUPER + CTRL + M` | System monitor |
| `SUPER + CTRL + Q` | Quick settings |
| `SUPER + SPACE` | Apps menu |
## Applications
| Keys | Action |
| --- | --- |
| `SUPER + ALT + SHIFT + F` | File manager (cwd) |
| `SUPER + RETURN` | Terminal |
| `SUPER + SHIFT + ALT + B` | Browser (private) |
| `SUPER + SHIFT + B` | Browser |
| `SUPER + SHIFT + D` | Docker |
| `SUPER + SHIFT + F` | File manager |
| `SUPER + SHIFT + G` | Signal |
| `SUPER + SHIFT + M` | Music |
| `SUPER + SHIFT + N` | Editor |
| `SUPER + SHIFT + O` | Obsidian |
| `SUPER + SHIFT + RETURN` | Browser |
## Tiling
| Keys | Action |
| --- | --- |
| `ALT + SHIFT + TAB` | Focus on previous window |
| `ALT + TAB` | Focus on next window |
| `CTRL + ALT + DELETE` | Close all windows |
| `CTRL + ALT + SHIFT + TAB` | Focus on previous monitor |
| `CTRL + ALT + TAB` | Focus on next monitor |
| `SUPER + ALT + code:20` | Expand window left a little |
| `SUPER + ALT + code:21` | Shrink window left a little |
| `SUPER + ALT + DOWN` | Move window to group on bottom |
| `SUPER + ALT + F` | Full width |
| `SUPER + ALT + G` | Move active window out of group |
| `SUPER + ALT + Home` | Save window width |
| `SUPER + ALT + LEFT` | Move window to group on left |
| `SUPER + ALT + mouse_down` | Next window in group |
| `SUPER + ALT + mouse_up` | Previous window in group |
| `SUPER + ALT + RIGHT` | Move window to group on right |
| `SUPER + ALT + S` | Move window to scratchpad |
| `SUPER + ALT + SHIFT + TAB` | Previous window in group |
| `SUPER + ALT + SLASH` | Monitor scaling down |
| `SUPER + ALT + TAB` | Next window in group |
| `SUPER + ALT + UP` | Move window to group on top |
| `SUPER + code:20` | Expand window left |
| `SUPER + code:21` | Shrink window left |
| `SUPER + CTRL + code:20` | Expand window left a lot |
| `SUPER + CTRL + code:21` | Shrink window left a lot |
| `SUPER + CTRL + F` | Tiled full screen |
| `SUPER + CTRL + LEFT` | Move grouped window focus left |
| `SUPER + CTRL + RIGHT` | Move grouped window focus right |
| `SUPER + CTRL + SHIFT + code:20` | Shrink window up a lot |
| `SUPER + CTRL + SHIFT + code:21` | Expand window down a lot |
| `SUPER + CTRL + TAB` | Former workspace |
| `SUPER + DOWN` | Focus on below window |
| `SUPER + F` | Full screen |
| `SUPER + G` | Toggle window grouping |
| `SUPER + Home` | Restore window width |
| `SUPER + J` | Toggle window split |
| `SUPER + L` | Toggle workspace layout |
| `SUPER + LEFT` | Focus on left window |
| `SUPER + mouse:272` | Move window |
| `SUPER + mouse:273` | Resize window |
| `SUPER + mouse_down` | Scroll active workspace forward |
| `SUPER + mouse_up` | Scroll active workspace backward |
| `SUPER + O` | Pop window out (float & pin) |
| `SUPER + P` | Pseudo window |
| `SUPER + RIGHT` | Focus on right window |
| `SUPER + S` | Toggle scratchpad |
| `SUPER + SHIFT + ALT + code:20` | Shrink window up a little |
| `SUPER + SHIFT + ALT + code:21` | Expand window down a little |
| `SUPER + SHIFT + ALT + DOWN` | Move workspace to down monitor |
| `SUPER + SHIFT + ALT + LEFT` | Move workspace to left monitor |
| `SUPER + SHIFT + ALT + RIGHT` | Move workspace to right monitor |
| `SUPER + SHIFT + ALT + UP` | Move workspace to up monitor |
| `SUPER + SHIFT + code:20` | Shrink window up |
| `SUPER + SHIFT + code:21` | Expand window down |
| `SUPER + SHIFT + DOWN` | Swap window down |
| `SUPER + SHIFT + LEFT` | Swap window to the left |
| `SUPER + SHIFT + RIGHT` | Swap window to the right |
| `SUPER + SHIFT + TAB` | Previous workspace |
| `SUPER + SHIFT + UP` | Swap window up |
| `SUPER + SLASH` | Monitor scaling up |
| `SUPER + T` | Toggle window floating/tiling |
| `SUPER + TAB` | Next workspace |
| `SUPER + UP` | Focus on above window |
| `SUPER + W` | Close window |
## Media
| Keys | Action |
| --- | --- |
| `ALT + SHIFT + XF86AudioPlay` | Previous track |
| `ALT + XF86AudioLowerVolume` | Volume down precise |
| `ALT + XF86AudioPlay` | Next track |
| `ALT + XF86AudioRaiseVolume` | Volume up precise |
| `ALT + XF86MonBrightnessDown` | Brightness down precise |
| `ALT + XF86MonBrightnessUp` | Brightness up precise |
| `SHIFT + XF86AudioMute` | Switch audio output |
| `SHIFT + XF86AudioPause` | Switch media source |
| `SHIFT + XF86AudioPlay` | Switch media source |
| `SHIFT + XF86MonBrightnessDown` | Brightness minimum |
| `SHIFT + XF86MonBrightnessUp` | Brightness maximum |
| `XF86AudioLowerVolume` | Volume down |
| `XF86AudioMicMute` | Mute microphone |
| `XF86AudioMute` | Mute |
| `XF86AudioNext` | Next track |
| `XF86AudioPause` | Pause |
| `XF86AudioPlay` | Play |
| `XF86AudioPrev` | Previous track |
| `XF86AudioRaiseVolume` | Volume up |
| `XF86Eject` | Eject media |
| `XF86KbdBrightnessDown` | Keyboard brightness down |
| `XF86KbdBrightnessUp` | Keyboard brightness up |
| `XF86KbdLightOnOff` | Keyboard backlight cycle |
| `XF86MonBrightnessDown` | Brightness down |
| `XF86MonBrightnessUp` | Brightness up |
| `XF86TouchpadOff` | Disable touchpad |
| `XF86TouchpadOn` | Enable touchpad |
| `XF86TouchpadToggle` | Toggle touchpad |
## Clipboard
| Keys | Action |
| --- | --- |
| `SUPER + C` | Universal copy |
| `SUPER + CTRL + V` | Clipboard manager |
| `SUPER + V` | Universal paste |
| `SUPER + X` | Universal cut |
## Utilities
| Keys | Action |
| --- | --- |
| `ALT + PRINT` | Screenrecording |
| `PRINT` | Screenshot |
| `SUPER + ALT + code:34` | Make webcam overlay smaller |
| `SUPER + ALT + code:35` | Make webcam overlay larger |
| `SUPER + ALT + comma` | Invoke last notification |
| `SUPER + ALT + SPACE` | Apps menu |
| `SUPER + BACKSPACE` | Toggle window transparency |
| `SUPER + comma` | Dismiss last notification |
| `SUPER + CTRL + A` | Audio |
| `SUPER + CTRL + ALT + B` | Show battery remaining |
| `SUPER + CTRL + ALT + D` | Calendar |
| `SUPER + CTRL + ALT + Delete` | Toggle laptop display mirroring |
| `SUPER + CTRL + ALT + R` | Show reminders |
| `SUPER + CTRL + ALT + T` | Show time |
| `SUPER + CTRL + ALT + W` | Toggle weather |
| `SUPER + CTRL + ALT + Z` | Reset zoom |
| `SUPER + CTRL + B` | Bluetooth |
| `SUPER + CTRL + BACKSPACE` | Toggle single-window square aspect |
| `SUPER + CTRL + C` | Capture menu |
| `SUPER + CTRL + comma` | Toggle silencing notifications |
| `SUPER + CTRL + D` | Display |
| `SUPER + CTRL + Delete` | Toggle laptop display |
| `SUPER + CTRL + E` | Emojis |
| `SUPER + CTRL + H` | Hardware menu |
| `SUPER + CTRL + I` | Toggle locking on idle |
| `SUPER + CTRL + L` | Lock system |
| `SUPER + CTRL + N` | Toggle nightlight |
| `SUPER + CTRL + O` | Toggle menu |
| `SUPER + CTRL + P` | Power |
| `SUPER + CTRL + PERIOD` | Transcode |
| `SUPER + CTRL + PRINT` | Extract text (OCR) from screenshot |
| `SUPER + CTRL + R` | Set reminder |
| `SUPER + CTRL + S` | Share |
| `SUPER + CTRL + SPACE` | Background switcher |
| `SUPER + CTRL + T` | Activity |
| `SUPER + CTRL + W` | Network |
| `SUPER + CTRL + Z` | Zoom in |
| `SUPER + ESCAPE` | System menu |
| `SUPER + K` | Keybindings |
| `SUPER + PRINT` | Color picker |
| `SUPER + SHIFT + ALT + comma` | Open notification history |
| `SUPER + SHIFT + BACKSPACE` | Toggle window gaps |
| `SUPER + SHIFT + code:201` | Blob menu |
| `SUPER + SHIFT + comma` | Dismiss all notifications |
| `SUPER + SHIFT + CTRL + R` | Clear reminders |
| `SUPER + SHIFT + CTRL + SPACE` | Theme menu |
| `SUPER + SHIFT + SPACE` | Toggle top bar |
| `SUPER + SPACE` | Blob menu |
| `XF86PowerOff` | Power menu |
## Unbound defaults
- `SUPER + SPACE`
- `SUPER + ALT + SPACE`
docs/shell.md
+91
View File
@@ -0,0 +1,91 @@
# The shell
`blob-shell` is one long-running Quickshell process hosting the bar, panels,
notifications, lock screen, OSD, and both menus. Everything runs inside it as a
plugin, so summoning a panel is an IPC call into a process that is already up.
## Layout
```
shell/
shell.qml entry point
Commons/ Style, Color, Border, Util
Ui/ shared components
services/ plugin registry, bar widget registry, app library
plugins/
bar/ the bar and its widgets
menu/ both menus
notifications/ daemon, popups, DND, history
notification-center/
lock/ polkit/ osd/ background/ clipboard/ emojis/
image-picker/ reminders/
panels/ audio bluetooth clock disk-speedtest monitor network
power quick-settings speedtest sysmon weather wifiqr
services/ battery idle media nightlight
```
First-party plugins are discovered under `shell/plugins` at a depth of two or
three and are enabled without being listed anywhere. Third-party plugins live in
`~/.config/blob/plugins/<id>/` and are enabled through `shell.json`.
## Config
`shell.json` is the whole bar config. It hot-reloads on save, and dragging a bar
widget rewrites `~/.config/blob/shell.json` directly, so after rearranging by
hand copy it back:
```
cp ~/.config/blob/shell.json shell.json
```
`./install.sh --check` reports the drift.
Defaults live at `config/blob/shell.json`. A valid user file replaces them
entirely rather than merging.
## Bar layout
| Section | Widgets |
| --- | --- |
| left | `blob.menu`, `blob.workspaces` |
| center | `blob.clock` (anchored), `blob.system-update` |
| right | `blob.tray`, `blob.bluetooth`, `blob.network`, `blob.audio`, `blob.monitor`, `blob.power`, `blob.notifications` |
`blob.clock` and `blob.notifications` are `type: "command"` modules, which is how
they carry their own click actions: the clock opens quick settings on left click,
the shell's calendar on middle, and the timezone picker on right; the bell opens
the notification centre on left and toggles silencing on right.
The centre module named by `centerAnchor` cannot be dragged out of the centre.
Every other widget still reorders.
## Differences from upstream
This shell was forked from Omarchy 4.0.4 and is not tracked against it. The
changes beyond renaming:
- `agents`, `tailscale`, `dropbox`, and `dev-gallery` plugins removed, about
7,000 lines.
- The `Dictation` bar indicator removed with voice typing.
- Persistent workspaces 1-9 instead of 1-5.
- Menu cards 440 wide instead of 300, with the Blob icon on the bar button.
- The lock screen carries `branding/screensaver.txt` and an AGS-style password
field: square corners, a 2px border on the blue slot at half alpha going to
solid accent once typing starts, and urgent on a failed attempt.
- `quick-settings`, `sysmon`, and `notification-center` are new, ported from the
GTK widgets. See [widgets.md](widgets.md).
None of these are clones or overrides. They are edits to first-party source, so
there is no clone machinery and nothing to re-apply after an upstream release.
The fork base is recorded in [upstream.md](upstream.md).
## Debugging
```
journalctl --user -t blob-shell -f
blob-shell-restart
```
A QML error in a `service` plugin means that service never loads. For the lock
that leaves the machine unlockable rather than locked open, so test it with
`blob-shell lock lock` before trusting a change to it.
docs/themes.md
+68
View File
@@ -0,0 +1,68 @@
# Themes
A theme is a directory under `themes/` holding at minimum a `colors.toml`.
`blob-theme-set <name>` stages it, renders every template against it, and
retints the running desktop.
## What a theme can ship
| File | Used by |
| --- | --- |
| `colors.toml` | required; the palette everything else derives from |
| `backgrounds/` | the background switcher |
| `shell.lock.toml` | lock screen surface tokens |
| `neovim.lua` | the editor colorscheme |
| `icons.theme` | GTK icon theme name |
| `preview.png`, `unlock.png`, `preview-unlock.png` | theme and lock previews |
## colors.toml
Named keys are preferred: `background`, `foreground`, `accent`, `muted`,
`selection`, the eight base colors, and their `bright_` variants. The pywal
`color0`..`color15` form also works and is resolved through the same cascade:
`color0` is the background, `color4` is blue, `color5` is magenta.
That cascade lives in `blob-theme-color`, and `Commons/Color.qml` mirrors it so
the shell and the CLI never disagree about what a slot means.
## Templates
`default/themed/*.tpl` are rendered per theme into
`~/.local/state/blob/current/theme/`. Nine ship: foot, kitty, btop, chromium,
hyprland, the screenshare picker, neovim, `shell.toml`, and zen.
An app picks its colors up in one of two ways. Most include the generated file
directly, so nothing has to run:
```
include ~/.local/state/blob/current/theme/kitty.conf
```
Zen does the same through a CSS import in `userChrome.css`. The rest are pushed
by a short applier listed in `post_theme_commands` inside `blob-theme-set`:
`blob-theme-foot`, `blob-theme-browser`, `blob-restart-terminal`,
`blob-restart-btop`, `blob-hypr-restart`.
Adding a template for another app means dropping a `.tpl` in `default/themed/`
and, if it cannot include a file, adding an applier to that list.
## The three ways to set a theme
| Command | Does |
| --- | --- |
| `blob theme menu` | pick from the bundled and local sets |
| `blob theme set <name>` | apply one by name |
| `blob wallpaper set <image>` | extract a palette from a wallpaper with pywal, fix flat palettes with `blob-theme-contrast`, and apply it as `blob-dynamic` |
| `blob theme share <link>` | fetch a shared palette and apply it as `blob-dynamic` |
Aether is also installed and does the same job with a GUI. To have its palettes
land where these do, add Blob as a custom app in Aether with a template writing
`colors.toml` into `~/.local/state/blob/current/theme/` and a post-apply hook
calling `blob-theme-refresh`.
## Bundled themes
Twenty-two came across from upstream, plus `flats` and `pitch-dark`. Their
`backgrounds/` directories are empty on purpose: the upstream images were
Omarchy branding, and `~/wallpapers` holds 103 of your own. A theme with no
background of its own leaves the current wallpaper alone.