Skip to main content

CLI reference

pmux intercepts a small set of Pocketmux-specific commands and passes everything else to tmux -L pmux. You can use pmux as a drop-in replacement for tmux with zero learning curve.

Command summary​

CommandDescription
pmux initGenerate identity and create configuration
pmux pairPair with a mobile device (displays QR code)
pmux configShow effective configuration with value sources
pmux statusShow agent and pairing status
pmux unpairRemove the paired mobile device
pmux uninstallRemove Pocketmux completely (reverses init)
pmux updateCheck for and install the latest version
pmux agent runRun the agent in the foreground
pmux agent startStart the agent
pmux agent stopStop the agent
pmux agent restartRestart the agent
pmux agent statusShow agent process status and recent logs
pmux --versionShow version
pmux --helpShow help

pmux init​

pmux init

One-time setup. Creates the ~/.config/pmux/ directory structure, generates an Ed25519 identity keypair, and writes a default config.toml. You are prompted for a host name (defaults to your OS hostname). See the Initialization guide for a walkthrough.

If an identity already exists, the command prints the existing device ID and exits without overwriting anything.

Init discovers the absolute path to the tmux binary and saves it as tmux.tmux_path in config.toml. This ensures the agent can find tmux even when spawned non-interactively, where $PATH may be minimal. If tmux is not found in $PATH, a warning is printed with instructions to set the path manually.

There is no separate service to install — the agent starts automatically (and idempotently) whenever you run any pmux command.

pmux pair​

pmux pair

Pairs the host with a mobile device. Contacts the signaling server, then displays a QR code and a manual pairing code in the terminal. The command waits up to 5 minutes for the mobile app to scan the code and complete the key exchange.

If a device is already paired, you are prompted to confirm replacement before proceeding. The background agent is stopped during pairing to prevent WebSocket conflicts, and restarts automatically on your next pmux command.

Requires pmux init to have been run first. See the Pairing guide for details.

pmux config​

pmux config

Displays the effective configuration with annotations showing where each value came from: default, file (config.toml), or env (environment variable). Example output:

name = "my-macbook"  (file)
log_level = "info"  (default)
server.url = "https://signal.pmux.io"  (default)
server.api_version = "v1"  (default)
identity.key_path = "~/.config/pmux/keys/"  (default)
identity.secret_backend = "auto"  (default)
connection.reconnect_interval = "5s"  (default)
connection.keepalive_interval = "30s"  (default)
connection.max_mobile_connections = 1  (default)
connection.force_relay = false  (default)
tmux.socket_name = "pmux"  (default)
tmux.tmux_path = "/opt/homebrew/bin/tmux"  (file)
update.enabled = true  (default)
update.check_interval = "24h"  (default)
power.keep_awake = false  (default)

See the Configuration reference for details on each field.

pmux status​

pmux status

Shows a comprehensive overview of the agent, tmux sessions, and paired device. Example output:

Version:  0.1.0-dev
Agent:    running (PID 48210)
Sessions: 3

Paired device: My iPhone
  Device ID:  a1b2c3d4e5f6...
  Paired:     2026-02-28

If a firewall is suspected of blocking inbound peer-to-peer connections, a warning line is printed after the session count.

If no device is paired, prints a reminder to run pmux pair.

pmux unpair​

pmux unpair

Removes the paired mobile device and clears its shared secret from local storage. You are prompted to confirm before the device is removed:

Unpair device 'My iPhone' (a1b2c3d4e5f6...)?
This device will need to scan a new QR code to reconnect. [y/N]

After unpairing, the device must scan a new QR code (via pmux pair) to reconnect. If no device is paired, prints "No device paired."

pmux uninstall​

pmux uninstall [--keep-config] [--yes|-y]

Completely removes Pocketmux from the system, reversing everything pmux init set up. Stops the agent if running, un-registers the host from the signaling server, and deletes the ~/.config/pmux/ directory including keys, paired device data, PID file, and log.

You are prompted to confirm before anything is removed. Pass --yes (or -y) to skip the confirmation prompt.

The --keep-config flag preserves config.toml while still removing keys and paired device data. This is useful if you want to re-initialize without losing your configuration settings.

pmux update​

pmux update

Checks for a newer release and installs it if one is available. Prints pmux is up to date when already on the latest version. The install method (GitHub release or Homebrew) is detected automatically; for self-update methods the agent is stopped before the binary is replaced and restarts on your next pmux command.

pmux agent​

The agent command group manages the background WebRTC agent process directly. Most users won't need these -- the agent starts automatically when you run any pmux command.

pmux agent run​

pmux agent run [--cpuprofile FILE] [--memprofile FILE]

Runs the agent in the foreground. This is primarily used internally (the supervisor spawns the agent this way) and for debugging. The optional profiling flags write Go pprof output to the specified files.

pmux agent start​

pmux agent start

Starts the agent by spawning a detached background process. If the agent is already running, prints its PID and exits.

pmux agent stop​

pmux agent stop

Stops the background agent process. Sends SIGTERM and waits up to 5 seconds for graceful exit, falling back to SIGKILL.

pmux agent restart​

pmux agent restart

Stops the agent and starts it again — equivalent to pmux agent stop followed by pmux agent start. If the agent is not running, it is simply started (this is not treated as an error). If the stop step fails, the agent is not restarted.

pmux agent status​

pmux agent status

Shows the version, whether the agent process is running, its PID, uptime, and the last 5 lines of the agent log. Example output:

pmux 0.1.0-dev
Agent is running (PID 48210)
Uptime: 02:34:17

Recent log:
  2026-02-28T09:30:01Z INF signaling connected
  2026-02-28T09:30:02Z INF webrtc peer connected device=a1b2c3d4e5f6
  ...

If the agent is not running, prints "Agent is not running" and exits with code 1. Stale PID files are cleaned up automatically.

pmux --version​

pmux --version
pmux -v

Prints the version string, e.g. pmux version 0.1.0-dev.

pmux --help​

pmux --help
pmux -h

Prints a summary of all Pocketmux commands and common tmux passthrough examples.

tmux passthrough​

Any command not listed above is forwarded directly to tmux -L <socket> [args...]. The background agent is automatically started if it is not already running. Examples:

pmux ls                    # list sessions
pmux attach -t work        # attach to session
pmux split-window -h       # split pane horizontally
pmux send-keys "ls" Enter  # send keystrokes to pane
pmux kill-server           # stop tmux server and agent

Socket isolation​

pmux uses the -L pmux flag to create a dedicated tmux socket. Sessions created with pmux are completely separate from your regular tmux sessions. Running pmux kill-server stops only the pmux tmux server; your regular tmux sessions are unaffected.

Running with no arguments​

Running bare pmux with no arguments starts a new tmux session (equivalent to tmux -L pmux new-session) and ensures the background agent is running. This is the simplest way to get started after pairing.