GSR-CLI(1) GPU Screen Recorder CLI Manual GSR-CLI(1)

gsr-cli - Control a running GPU Screen Recorder instance

gsr-cli -ipc socket_path command [command_arguments...]

gsr-cli -h | --help

gsr-cli sends a command to a gpu-screen-recorder(1) instance that was started with the -ipc option and reports the reply. This gives the same control as sending signals to GPU Screen Recorder, except that a replay can be saved with an arbitrary number of seconds and that the result of the command is known instead of being sent blindly.

gsr-cli exits with 0 when the command succeeded and 1 when it failed. When a command fails the reason is printed to stderr.

The unix domain socket that GPU Screen Recorder was started with. Required.

Check if a GPU Screen Recorder instance is listening on the socket, which is done by connecting to the socket without sending a command. Prints running or not running and exits with 0 when it's running. A socket file that was left behind by a GPU Screen Recorder instance that was killed counts as not running.
Stop and save recording (stop without save in replay mode). Waits until the recording has been saved and prints the path of the saved file. Nothing is printed in replay mode since nothing is saved.
Pause/unpause recording (not for streaming/replay).
Pause/unpause recording (not for streaming/replay). Unlike toggle-pause this doesn't fail when the recording is already paused/unpaused, so the result doesn't depend on the current state.
Start/stop regular recording during replay/streaming, which requires GPU Screen Recorder to run with the -ro option.
Start regular recording during replay/streaming, which requires GPU Screen Recorder to run with the -ro option. Does nothing when a recording is already running.
Stop the regular recording that runs during replay/streaming. Waits until the recording has been saved and prints the path of the saved file. Fails when no recording is running.
Save replay (replay mode only). The number of seconds has to be larger than 0. The whole replay buffer is saved when no number of seconds is given. Waits until the replay has been saved and prints the path of the saved file. restart-replay overrides the -restart-replay-on-save option of GPU Screen Recorder for this save, which clears the replay buffer after the whole replay buffer has been saved.

Start GPU Screen Recorder in replay mode with an ipc socket:

gpu-screen-recorder -w screen -f 60 -c mp4 -r 60 -o ~/Videos -ipc "$XDG_RUNTIME_DIR/gsr.sock" &

Save the last 30 seconds:

gsr-cli -ipc "$XDG_RUNTIME_DIR/gsr.sock" save-replay 30

Save the whole replay buffer and clear it:

gsr-cli -ipc "$XDG_RUNTIME_DIR/gsr.sock" save-replay restart-replay=true

Start replay only when it isn't already running:

gsr-cli -ipc "$XDG_RUNTIME_DIR/gsr.sock" status >/dev/null || start-replay.sh

  • The socket can only be used by the user that started GPU Screen Recorder.
  • The stop, save-replay and stop-replay-recording commands are replied to when the file has been saved and the script given with the -sc option has been started, and the reply contains the path of the saved file. The other commands are replied to as soon as GPU Screen Recorder accepts them.
  • GPU Screen Recorder creates the socket before it has finished starting up, so a command that is sent while it's starting up is replied to when the recording starts.

gsr-cli was written by the GPU Screen Recorder contributors.

Report bugs to: dec05eba@protonmail.com.

Copyright © dec05eba. Licensed under GPL-3.0-only.

gpu-screen-recorder(1)

Project homepage: https://git.dec05eba.com/gpu-screen-recorder/about/

2026-08-02 5.15.3