Command Line (polyctl)

polyctl is a small command-line tool that talks to a running PolyKybdHost daemon over its local control socket. It is stdlib-only and never imports Qt, which makes it ideal for headless machines, scripted setups, and quick one-off commands without opening the tray GUI.

Note

polyctl controls an existing daemon — it does not start one. The one exception is polyctl logs, which works whether or not anything is running. Launch the daemon first with python -m polyhost (GUI + daemon) or python -m polyhost --headless (no GUI). See Daemon & Client Model.

Subcommands

Command	Description
status	Show connection state and current keyboard status
lang list / lang set <code>	List available languages, or switch the active language
brightness <value>	Set display brightness
brightness --auto	Hand brightness back to automatic — a manual level otherwise sticks until you do. With adaptive daylight off there is no automatic source to return to, so it just clears the override and restores the keyboard’s stored level.
idle <…>	Configure or trigger idle behaviour
idle-style [pulse|jitter|eden]	Get or set the idle anti-burn-in style
idle-timeout [15sec|30sec|45sec|1min|2min|5min]	Get or set how long before the keycaps start fading — the delay before the style above engages, not the display-off deadline
glyph-script [standard|tengwar|…]	Get or set the glyph-script legend override
glyph-size [small|medium|large]	Get or set the legend size — how large a key’s main legend is drawn
fontpack status|sync|flash <id>|wipe [id]	Inspect and manage the font-pack bundles
overlay …	Inspect and manage key overlays
keymap …	Read/write the dynamic keymap
macro list|get <id>|set <id> …|clear <id>	Read and write the keyboard’s macros — set takes --text (plain characters) or --script (chords and pauses in VIA’s syntax), plus --label, --style (index/icon/text/icononly) and --icon; list also reports how much of the shared store is in use
crash show [--slave] [--json] / crash clear	Read (or forget) the keyboard’s last firmware crash record — what it was doing when it faulted or hung, and where; --slave asks for the link-side half’s record
commands	List the keyboard’s available one-off commands
fw version	Report the keyboard’s firmware version
fw flash <bin> [--apply]	Flash a firmware .bin over HID (streams progress)
pause / resume	Suspend or resume the daemon’s device I/O
mru save	Ask the keyboard to persist its recently-used emoji / language picks
settings get <key> / settings set <key> <value>	Read or change a setting (e.g. settings set developer_mode true — restart the app for the Developer submenu to appear)
update check / update install	Check for and install host updates (streams progress)
telemetry status|preview|enable|disable|send	Inspect or turn off the anonymous usage report — preview prints the exact report that would be sent
unicode-mode	Re-detect the host’s unicode input method (WinCompose vs native) and push it to the keyboard
logs bundle|show|paths|clear	Collect the log files — write a support .zip, print recent lines, list what was found, or empty them all (clear asks first; -y skips the prompt). Works with the host stopped — see Reporting a Problem
window report	Report the current active window to the daemon
watch	Stream live events from the daemon to the terminal
shutdown	Stop the daemon

Long-running operations (fw flash, update install) subscribe to daemon events and stream their progress to the terminal as it happens.

Examples

Caution

These are illustrative examples. Run polyctl <command> --help for the exact, current argument syntax of any subcommand.

# Check the daemon is alive and the keyboard is connected
polyctl status

# Switch the active language
polyctl lang set en-US

# Set display brightness
polyctl brightness 80

# ...and give control back to the automatic/daylight source
polyctl brightness --auto

# Flash firmware and apply it immediately
polyctl fw flash firmware.bin --apply

# Stream live events (reconnects, overlay sends, window changes)
polyctl watch

# Collect a support bundle (this one works even if the host is not running)
polyctl logs bundle --since 2h

# Start from a clean slate before reproducing something (asks for confirmation)
polyctl logs clear

# Adopt the daemon-by-default startup model
polyctl settings set daemon_mode true

Because polyctl speaks the same control protocol the tray GUI uses, you can mix the two freely — drive a headless daemon from scripts and attach the GUI later with python -m polyhost --connect when you want a window.