---
name: "gsr-cli"
section: "1"
platform: "linux"
package: "gpu-screen-recorder"
version: "6.1.6-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/gsr-cli"
---

# gsr-cli(1)

Control a running GPU Screen Recorder instance

## NAME

gsr-cli - Control a running GPU Screen Recorder instance

## SYNOPSIS

**gsr-cli** **-ipc** *socket\_path* *command* \[*command\_arguments...*\]

**gsr-cli** **-h** \| **--help**

## DESCRIPTION

**gsr-cli** sends a command to a [**gpu-screen-recorder**(1)](/gpu-screen-recorder/1.md) 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.

## OPTIONS

- **-ipc** *socket\_path*

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

## COMMANDS

- **status**

  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**

  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.

- **toggle-pause**

  Pause/unpause recording (not for streaming/replay).

- **set-paused** true\|false

  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.

- **toggle-replay-recording**

  Start/stop regular recording during replay/streaming, which requires GPU Screen Recorder to run with the **-ro** option.

- **start-replay-recording**

  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-replay-recording**

  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** \[***seconds***\] \[**restart-replay=true\|false**\]

  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.

## EXAMPLES

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
```

## NOTES

- •

  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.

## AUTHORS

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

## REPORTING BUGS

Report bugs to: dec05eba@protonmail.com ⟨mailto:dec05eba@protonmail.com⟩.

## COPYRIGHT

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

## SEE ALSO

[**gpu-screen-recorder**(1)](/gpu-screen-recorder/1.md)

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