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, service, and pairing status
pmux unpairRemove the paired mobile device
pmux uninstallRemove Pocketmux completely (reverses init)
pmux agent runRun the agent in the foreground
pmux agent startStart the agent
pmux agent stopStop the agent
pmux agent statusShow agent process status and recent logs
pmux agent installInstall as OS service (auto-start on login)
pmux agent uninstallRemove OS service registration
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 when launched by a service manager where $PATH may be minimal. If tmux is not found in $PATH, a warning is printed with instructions to set the path manually.

Init also installs the agent as an OS service (launchd on macOS, systemd on Linux) so the agent starts automatically on login and restarts on crash. If service installation fails, the agent will still start on-demand when you run pmux commands.

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)
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)
tmux.socket_name = "pmux"  (default)
tmux.tmux_path = "/opt/homebrew/bin/tmux"  (file)

See the Configuration reference for details on each field.

pmux status​

pmux status

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

Agent:    running (PID 48210)
Service:  installed
Sessions: 3

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

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]

Completely removes Pocketmux from the system, reversing everything pmux init set up. Uninstalls the OS service, stops the agent if running, and deletes the ~/.config/pmux/ directory including keys, paired device data, PID file, and log.

You are prompted to confirm before anything is removed.

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 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 by the service manager and for debugging. The optional profiling flags write Go pprof output to the specified files.

pmux agent start​

pmux agent start

Starts the agent. Uses the OS service manager if a service is installed, otherwise spawns a detached background process directly. If the agent is already running, prints its PID and exits.

pmux agent stop​

pmux agent stop

Stops the background agent process. If a service is installed, stops through the service manager (which prevents auto-restart). Otherwise, sends SIGTERM and waits up to 5 seconds for graceful exit, falling back to SIGKILL.

pmux agent status​

pmux agent status

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

Agent is running (PID 48210)
Service: installed
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 agent install​

pmux agent install

Installs the agent as an OS service that starts automatically on login and restarts on crash. On macOS, this creates a launchd plist at ~/Library/LaunchAgents/io.pmux.agent.plist. On Linux, this creates a systemd user service at ~/.config/systemd/user/pmux.service.

pmux agent uninstall​

pmux agent uninstall

Removes the OS service registration. The agent will no longer start automatically on login. You can still start it manually with pmux agent start or by running any pmux command.

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.