Command Line (polyctl)

polyctl is a small command-line tool that talks to a running PolyKybdHost daemon over its local control socket. It needs no GUI, so it suits headless machines, scripts and quick one-off commands.

Note

polyctl controls an existing daemon — it does not start one. Two commands work whether or not anything is running: polyctl logs, and polyctl shell-integration, which reads your shell startup files (status) or edits them (install, remove) and nothing else. 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	Return brightness to automatic control. Otherwise a manual level stays set. With adaptive daylight off, it restores the keyboard’s stored level.
idle <…>	Configure or trigger idle behaviour
idle-style [pulse|jitter|eden|iddqd]	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 starts, 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 send <file…>|enable|disable|reset	Send overlay image files to the keyboard, switch overlays on or off, or clear the ones it holds
keymap layer-count|layer-names|default-layer|buffer / keymap set <layer> <row> <col> <keycode>	Read the dynamic keymap, or write one key without touching the rest (the keycode is decimal or 0x hex)
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 delete) 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
reboot	Restart both keyboard halves. Nothing is saved. Needs firmware protocol 22 (firmware 1.7.0) or later
bootloop [--rounds N] / bootloop --cancel	Reboot the keyboard up to N times (default 50, at most 9999) and stop at the first boot that left a crash record or did not finish starting within a minute. Needs firmware protocol 22
handedness left|right	Tell the keyboard which half is which, when a half has started as the wrong side. Name the side of the half the USB cable is plugged into; the other half becomes the opposite. Both halves save their handedness stamp and restart with the new setting (about 10 s, no replug). Check the result on the keyboard: the command only confirms that the request was sent. Needs host 1.3.0 or later. --split-vbus on|off also sets or removes the old Rev.2 board mark on the connected half only; it needs firmware 1.9.12 and host 1.17.49 (protocol 24)
commands <file>	Run device commands from a file, one command per line
newer-policy ignore|safe	Choose what the host does with a keyboard whose firmware is newer than the host knows. ignore connects fully; safe allows only firmware update and debugging
replay-anim	Replay the one-time startup animation on the keycaps
doom install <whx> / doom install-pack <plyx>	Install the DOOM game data, or the engine pack, on both halves. The engine pack must match the firmware build
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
shell-integration install|remove|status	Make bash, zsh and PowerShell put the running command into the terminal title, so the host can show the GNU nano overlay. It edits your shell startup files and needs no running host. Needs host 1.17.82
logs bundle|show|paths	Collect the log files: write a support .zip, print recent lines, or list what was found. 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

Because polyctl uses 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.