Commands

This page covers the pypr command-line interface and available commands.

Overview

The pypr command operates in two modes:

Usage	Mode	Description
pypr	Daemon	Starts the Pyprland daemon (foreground)
pypr <command>	Client	Sends a command to the running daemon

There is also an optional pypr-client command which is designed for running in keyboard-bindings since it starts faster but doesn't support every built-in command (eg: validate, edit).

TIP

Command names can use dashes or underscores interchangeably. E.g., pypr shift_monitors and pypr shift-monitors are equivalent.

Built-in Commands

These commands are always available, regardless of which plugins are loaded:

Loading commands...

Plugin Commands

Each plugin can add its own commands. Use pypr help to see the commands made available by the list of plugins you set in your configuration file.

Examples:

• scratchpads plugin adds: toggle, show, hide
• magnify plugin adds: zoom
• expose plugin adds: expose

See individual plugin documentation for command details.

Shell Completions

Pyprland can generate shell completions dynamically based on your loaded plugins and configuration.

Generating Completions

With the daemon running:

# Output to stdout (redirect to file)
pypr compgen zsh > ~/.zsh/completions/_pypr

# Install to default user path
pypr compgen bash default
pypr compgen zsh default
pypr compgen fish default

# Install to custom path (absolute or ~/)
pypr compgen bash ~/custom/path/pypr
pypr compgen zsh /etc/zsh/completions/_pypr

WARNING

Relative paths may not do what you expect. Use default, an absolute path, or a ~/ path.

Default Installation Paths

Shell	Default Path
Bash	~/.local/share/bash-completion/completions/pypr
Zsh	~/.zsh/completions/_pypr
Fish	~/.config/fish/completions/pypr.fish

TIP

For Zsh, the default path may not be in your $fpath. Pypr will show instructions to add it.

NOTE

Regenerate completions after adding new plugins or scratchpads to keep them up to date.

pypr-client

pypr-client is a lightweight, compiled alternative to pypr for sending commands to the daemon. It's significantly faster and ideal for key bindings.

When to Use It

• In hyprland.lua key bindings where startup time matters
• When you need minimal latency (e.g., toggling scratchpads)

Limitations

• Cannot run the daemon (use pypr for that)
• Does not support validate or edit commands (these require Python)

Installation

Depending on your installation method, pypr-client may already be available. If not:

1. Download the source code
2. Compile it: gcc -o pypr-client pypr-client.c

Rust and Go versions are also available in the same directory.

Usage in hyprland.lua

--Use pypr-client for faster key bindings
local pypr = "/usr/bin/pypr-client"

--example bindings
hl.bind(mainMod .. " + A", hl.dsp.exec_cmd(pypr .. " toggle term"))
hl.bind(mainMod .. " + B", hl.dsp.exec_cmd(pypr .. " expose"))
hl.bind(mainMod .. " + Z", hl.dsp.exec_cmd(pypr .. " zoom"))

TIP

If using uwsm, wrap the command:

local pypr = "uwsm-app -- /usr/bin/pypr-client"

For technical details about the client-daemon protocol, see Architecture: Socket Protocol.

pypr-gui

pypr-gui is a web-based configuration editor. It starts a local HTTP server and opens a browser interface for viewing and editing your pyprland configuration.

Features

• Plugin browser: enable/disable plugins with checkboxes
• Schema-driven forms: each plugin's options are presented with types, defaults, descriptions, and validation
• Validate / Save / Apply: check your config for errors, save to disk, or save and live-reload the running daemon in one click
• Multi-file support: saves per-plugin files under conf.d/, keeping your configuration tidy (see Multiple Configuration Files)

Usage

pypr-gui              # Start server and open browser
pypr-gui -s           # Print URL (start server in background if needed)
pypr-gui -w           # Open browser (explicit, same as default)
pypr-gui --no-browser # Start server without opening browser
pypr-gui --port 9000  # Use a specific port (default: 18099)

The server listens on 127.0.0.1:18099 by default (not exposed to the network). If an instance is already running, pypr-gui will reuse it instead of starting a new one.

NOTE

The pyprland daemon does not need to be running to edit and validate your configuration. However, the Apply action (save + reload) requires a running daemon.

Debugging

To run the daemon with debug logging:

pypr --debug

To also save logs to a file:

pypr --debug $HOME/pypr.log

Or in hyprland.lua:

hl.exec_cmd('/usr/bin/pypr --debug $HOME/pypr.log')

The log file will contain detailed information useful for troubleshooting.