umbractl command reference

umbractl is the command-line client. The installer puts it on your PATH; a portable copy has umbractl.exe next to Umbra.exe and talks to that copy. Every command prints JSON (a text result such as diagnostics prints as plain text), exits 0 on success and 1 with umbractl: <error> on stderr on failure. If Umbra isn’t running, it’s started in the background first. umbractl help prints this list.

<id> is a widget id, or a copy like sp500#2. Square brackets are optional.

Inspect

Command	What it does
status	Version, paths, open widgets, monitors and general settings
list	Widgets with their settings, option schema and window bounds
logs [n]	The last n log lines
diagnostics	Markdown block for bug reports: versions, monitors, enabled widgets, last 30 log lines. No option values, proxy address or widget data
privacy [id]	Hosts, commands, saved data and blocked requests per widget (read-only)
approvals [id]	Local commands widgets declare and whether you approved them (read-only)
check-update	Is a newer Umbra on GitHub? (it never installs)

Place and configure widgets

Command	What it does
enable <id> / disable <id>	Show or hide a widget
lock <id> / unlock <id>	Lock or unlock moving, resizing and zooming
move <id> <x> <y>	Position in physical pixels
reset-position <id>	Back to the default position
configure <id> [flags]	Change several settings at once (below)
set <id> <option> <value>	Change a widget option, typed by its schema
add-instance <id>	Run another copy (own options, position, data); ids look like sp500#2
remove-instance <id#N>	Remove an extra copy and its data
refresh [id]	Fetch fresh data now
reload	Re-scan widget folders

configure flags:

Flag	Values
--scale	0.5–3, or a percent like 150% (size and zoom)
--enabled, --locked	on or off
--x, --y	Position in physical pixels
--monitor	A monitor number from status, or primary (the widget keeps its offset and survives monitor changes)
--refresh	30–600 seconds, or default
--opacity	0.2–1, or opaque
--start-hidden	on or off
--show-from, --show-to	HH:MM daily range; --show-from always clears it
--show-on-ac	on or off

Arrange

Command	What it does
edit-mode [on|off]	Move, resize and zoom by hand; no argument reads the state
peek [seconds]	Raise widgets above other windows for a few seconds (never takes focus)
safe-mode [on|off]	Community widgets off, not saved; no argument shows the state
layouts [list|save|apply|delete <name>|rename <name> <new>]	Saved arrangements of positions, sizes and enabled widgets
groups [list|create <id> [name]|join|activate <group> <id>|leave <id>|next|previous|delete <group>|reorder <group> <id> <i>|cycle <group> <s|off>|rename <group> <name>|icon <id> <name|default>]	Tab groups: widgets sharing one spot, one visible at a time
hotkeys [action keys|off|reset]	Global hotkeys: edit-mode, refresh-all, toggle-widgets, peek, open-settings, e.g. hotkeys edit-mode Ctrl+Alt+E

App settings

general (alias of the protocol’s set-general) changes app-wide settings:

Flag	Values
--refresh	30–600 seconds
--animations, --startup, --updates, --hide-fullscreen, --energy-saver	on or off
--peek-seconds	1–60
--corner-radius	default, sharp, round
--animation-speed	normal, calm, off
--default-scale	0.5–3
--log-level	errors, normal, verbose
--developer-mode, --hardware-acceleration	on or off (GPU needs a restart)
--startup-delay	0–300 seconds
--proxy	system, none or https://host:port (needs a restart)
--snap	on or off (master switch)
--snap-mode	shift (default: snap only while Shift is held) or always (Shift skips snapping)
--snap-grid	0–200 px (0 = off)
--snap-edges	on or off
--snap-gap	0–100 px kept between neighbours (0 = touch)

Appearance flags: --accent "#ff7a59" (or windows, or empty for the theme), --light-text, --ui-font, --font-scale (0.8–1.4), --border, --reduce-transparency:

umbractl general --refresh 120 --snap-grid 20
umbractl general --corner-radius round --animation-speed calm --log-level verbose --proxy none
umbractl set-general --accent "#ff7a59" --light-text on --ui-font Consolas --font-scale 1.1 --border off --reduce-transparency on

Catalog and themes

Command	What it does
catalog	Community widgets on GitHub, with installed and update flags
install <id> [--accept-permissions]	Install or update a catalog widget. An update that adds hosts, media, notifications or commands is refused until you repeat it with the flag
remove <id>	Uninstall a catalog widget and delete its data for good
update --all	Update every installed catalog widget that has a newer version. Failures are listed and the rest still update; updates that add permissions are skipped and listed
themes	Installed themes and the community theme catalog
theme [id]	Show the active theme, or switch to an installed one (live; default is Umbra Black)
install-theme <id> / remove-theme <id>	Install, update or uninstall a community theme

Build and test widgets

Command	What it does
new <id> [--name N] [--dir D]	Scaffold a working widget (default: the community folder, loaded at once)
create <folder>	Load a widget folder from disk, e.g. widgets/my-widget in the repo
capture <id|settings:<page>> [file.png]	PNG of a widget or Settings page (general, widgets, layouts, browse, themes, hotkeys, privacy, about)
data <id> [key] [json]	A widget’s saved data (umbra.store): all, one key, or set a key
data <id> --remove <key> / --clear	Delete a key, or everything
settings [page]	Open the Settings window

Back up

Command	What it does
backup <file>	Settings, layout, theme, hotkeys and widget data (never approvals)
restore <file>	Restore from a backup; validated first, approvals are not restored

Other

Command	What it does
quit	Exit Umbra
send <command> [json]	A raw control-protocol command, e.g. umbractl send install-theme '{"id":"ember"}'
mcp	Run as an MCP server on stdio
help	The built-in help

Note

umbractl remove and the MCP remove_widget delete for good. Only Settings → Remove keeps a widget in the trash for 7 days with Undo.