Host CLI

Look up a punktfunk-host command or flag here. Most behaviour comes from host.env, not the command line; a flag wins over its host.env twin.

punktfunk-host --help prints the common commands. ctl, plugins, service, tray, driver and web print their usage when run with no arguments.

serveCopy Anchor Link

Runs the native punktfunk/2 host and the management API in one process. The native plane always runs.

punktfunk-host serve

Pairing is required unless --open: arm it from the web console — see Pairing & Trust.

The management API is HTTPS and listens on every interface by default. Off loopback it serves paired clients the read-only status and library. Every admin action needs the token in mgmt-token and works from loopback only. The host writes that file on first start into its config directory (~/.config/punktfunk, or %ProgramData%\punktfunk on Windows); the console, ctl and the tray read it. Every endpoint is in the API Reference.

ctlCopy Anchor Link

Drives a running host over loopback: everything the web console does day to day, from a terminal.

punktfunk-host ctl pending
punktfunk-host ctl approve 3

In stats, Target is the encoder's bitrate; Sent is what left the box and exists only while a capture records. A still screen sends little, so read new fps beside repeated fps.

Add --json to any verb: {"v":1,"data":…} on success, {"v":1,"error":{"code":…,"message":…}} on failure, both on stdout. That envelope is stable; the human tables are not.

watch reconnects by itself and starts at the live tail (--since 0 replays the host's ring). It adds two lines of its own: {"kind":"ctl.resync"} means it fell behind, so re-read ctl status and ctl pending; {"kind":"ctl.disconnected"} means a reconnect is under way.

ctl reads the host's mgmt-token and pins its native-cert.pem before sending the token. It never creates a token and takes none on the command line or from the environment.

settingsCopy Anchor Link

punktfunk-host settings set gamestream true

Writes one Host value to host-settings.json, as the console does, without a running host. Installers use it, so the console can still change what they chose. The value is JSON (true, 30, null to clear) or a bare string. Restart the host to apply it.

pluginsCopy Anchor Link

punktfunk-host plugins add|remove|list|enable|disable|status|grant|access|revoke does what the console's Plugins page does. Plugins run with the host's privileges; read Plugins first.

libraryCopy Anchor Link

punktfunk-host library prints the game library as JSON, the same as GET /api/v1/library — the quick answer to "does the host see my games?". punktfunk-host library art --clear deletes the covers the host cached for clients.

punktfunk1-hostCopy Anchor Link

A standalone native-only host for testing the punktfunk/2 path, with no GameStream and no console. Pairing is required; it logs a PIN at startup.

punktfunk-host punktfunk1-host --source virtual

service (Windows)Copy Anchor Link

The installer runs service install; you need these only to change an option or nudge the service. Run them from an Administrator prompt.

punktfunk-host service install [--gamestream=on|off] [--allow-public-network[=on|off]]
                               [--mgmt-bind=IP:PORT] [--web-bind=ADDR]
punktfunk-host service start | stop | restart | status | uninstall

See Running as a Service and Windows Host.

tray (Windows)Copy Anchor Link

punktfunk-host tray start|stop|status brings the per-user status tray back after an update or a crash, without signing out. status says whether it is installed and running.

driver (Windows)Copy Anchor Link

The installer manages the drivers. These remove one without uninstalling the host:

punktfunk-host driver check                # does the virtual display driver answer?
punktfunk-host driver uninstall            # the virtual display driver
punktfunk-host driver uninstall --gamepad  # the virtual gamepad driver
punktfunk-host driver uninstall --audio    # the host's virtual speaker and microphone devices

seats (Windows)Copy Anchor Link

punktfunk-host seats off, run elevated, turns seats off without the service: Remote Desktop's listener and firewall rules and the shared Steam shortcuts go back to how they were before seats, and the seat listener goes. The seat accounts stay. Uninstalling runs it; while the host runs, use Profiles → Seats instead, which also stops the seats first.

web (Windows)Copy Anchor Link

punktfunk-host web password prints the web console login password. Run it elevated: the file is readable by Administrators and SYSTEM only. A silent install (winget, /VERYSILENT) shows the password nowhere else.

list-monitorsCopy Anchor Link

Prints the physical monitors by connector name, the name PUNKTFUNK_CAPTURE_MONITOR takes to stream a real monitor. Run it inside the session you want to stream.

$ punktfunk-host list-monitors
Kwin:
  HDMI-A-1        1920x1080@60 at +0,+0    scale 1  Dell U2412M  [primary]
  DP-2            2560x1440@144 at +1920,+0  scale 1  ACME 27  [PINNED]

Tags: primary, disabled, punktfunk virtual display (one of the host's own), PINNED (the current pick).

punktfunk-host mirror-test --monitor <CONNECTOR> [--seconds N] [--cpu] captures that monitor with no client and reports the first frame, the frame count and the size. Move the mouse while it runs: a still screen produces almost no frames.

punktfunk-host anchor-test --monitor <CONNECTOR> [--width W --height H] walks the pointer to the centre and four corners of that monitor, one second apart; --none walks it unanchored for comparison. The log line libei: absolute input maps into this output names the monitor it hit. It needs the libei input backend (GNOME, or PUNKTFUNK_INPUT_BACKEND=libei).

hdr-probe and probe-compositorCopy Anchor Link

Linux checks that need no client.

punktfunk-host hdr-probe
punktfunk-host probe-compositor

hdr-probe answers "why isn't my stream HDR?": a monitor in HDR mode (GNOME), a punktfunk-gamescope with HDR on, 10-bit HEVC and AV1 encode, and the verdict for each plane. Run it with the host service's environment: HDR → Check it has the command and reads the output.

probe-compositor exits 0 once the compositor is ready, so a bring-up script can wait on it instead of a sleep. It checks KWin's screencast grant and Hyprland's hyprctl; other compositors pass once detected.

On Windows, hdr-p010-selftest checks the GPU's HDR capture conversion with no display or session, and prints PASS or FAIL with the largest error:

punktfunk-host hdr-p010-selftest 1920x1080 nvidia

Both arguments are optional: your capture size (default 64x64; 1080 takes a different driver path) and, on a dual-GPU box, the encoding vendor (intel, nvidia or amd).

detect-conflictsCopy Anchor Link

Lists Sunshine, Apollo and other Moonlight-compatible hosts installed on this machine. It exits 1 when one runs or starts on its own, 0 otherwise, so scripts can gate on it. Running one beside Punktfunk is unsupported: they fight over ports and the virtual display. serve runs the same check at startup. See Troubleshooting.

The client's punktfunk commandCopy Anchor Link

The machine you stream to has its own command, punktfunk. Its verbs and exit codes are on Clients → the punktfunk CLI; punktfunk wake is on Wake on LAN.