---
title: CLI
description: Get your token, send notifications, read and stream data, and run the backend from the terminal.
---

The System Bridge CLI provides commands to interact with the System Bridge backend. Most commands live under the `system-bridge client` subcommand, while `backend`, `version` and `completions` are top-level commands. Running `system-bridge` without a subcommand shows help.

## Token

The token is essential to connect to the API/WebSocket. To get it, run the following command:

```bash
system-bridge client token
```

:::note
The token is stored per user, so run this command as the same user that runs the backend. If you run System Bridge as a system service under root, switch to that user first:

```bash
sudo su -
system-bridge client token
```

You can also use the short form `system-bridge c t`.
:::

Alternatively, you can find your token in the application startup logs when running the backend. The logs will show "Your API token is" followed by your token value.

## Notification

To send a notification, use the following command:

```bash
system-bridge client notification --title "Title" --message "Message" --icon "icon-name"
```

Available flags:

- `--title`: The title of the notification (default: "System Bridge")
- `--message`: The message of the notification (default: "Hello, world!")
- `--icon`: The icon of the notification (default: "system-bridge")
- `--sound`: Path to a sound file to play with the notification (Linux only)
- `--action-url`: URL to open when the notification is clicked (Linux only)
- `--action-path`: File/folder path to open when the notification is clicked (Linux only)

## Web client

Open the web client in your browser, already connected to this system:

```bash
system-bridge client open
```

Add `--settings` to open General Settings, or `--path` to open any page, including a section of one:

```bash
system-bridge client open --path /media#media-controls
```

## Quit

Quit the local backend. It asks for confirmation first, unless you add `--yes`:

```bash
system-bridge client quit --yes
```

## Audio

Set an output's or input's volume in percent, mute or unmute it, or make it the default:

```bash
system-bridge client audio alsa_output.pci-0000_00_1f.3.analog-stereo --volume 40 --mute=false
```

The id is the device's `id` from the [`audio`](/api/data/#audio) data. Use `--mute` to mute it and `--default` to make it the default output or input. See [audio](/features/remote-control/#audio) for what each platform supports.

## Bluetooth

Connect, disconnect or forget a paired device, or turn Bluetooth on or off:

```bash
system-bridge client bluetooth connect 80:C3:BA:7B:93:4E
system-bridge client bluetooth disconnect 80:C3:BA:7B:93:4E
system-bridge client bluetooth forget 80:C3:BA:7B:93:4E
system-bridge client bluetooth power on
```

The address is the device's `address` from the [`bluetooth`](/api/data/#bluetooth) data. See [Bluetooth](/features/remote-control/#bluetooth) for what each platform supports.

## Clipboard

Put text on the backend system's clipboard, as an argument or piped in:

```bash
system-bridge client clipboard set "Some text"
echo "Some text" | system-bridge client clipboard set
```

It needs wl-clipboard on Wayland, or xclip or xsel on X11. Linux only.

## Commands

List the [commands](/features/commands/) on your list and the prefabs, and run one by its ID:

```bash
system-bridge client command list
system-bridge client command prefabs
system-bridge client command run 9ef69bc3-62f8-4d86-952d-5f498bbddf0f
```

`run` waits for the command to finish, prints its output, and exits with its exit code, so scripts can check it. Add `--json` to `list` or `prefabs` for JSON.

## Desktop

Focus, close or change a window, show a workspace, or switch the keyboard layout:

```bash
system-bridge client desktop focus 0x555dbf21c9e0
system-bridge client desktop close 0x555dbf21c9e0
system-bridge client desktop state 0x555dbf21c9e0 --fullscreen --maximised=false
system-bridge client desktop workspace 2
system-bridge client desktop layout us
```

The ids are the window and workspace `id`s from the [`desktop`](/api/data/#desktop) data. `state` takes `--fullscreen`, `--maximised` and `--minimised`, each turned off with `=false`. See [desktop](/features/remote-control/#desktop) for what each desktop supports.

## Discord

Control Discord voice, once [Discord is set up](/features/discord/):

```bash
system-bridge client discord toggle_mute
```

Actions that need nothing else work here, such as `mute`, `unmute`, `toggle_mute`, `deafen`, `undeafen`, `toggle_deafen`, `leave_voice_channel`, `toggle_video` and `toggle_screenshare`. Use the web client or the API for actions that take a channel, user, device or value.

## Displays

Set a display's brightness in percent, its power state, or both:

```bash
system-bridge client display HDMI-A-2 --brightness 40 --power on
```

The id is the display's `id` from the [`displays`](/api/data/#displays) data. The power state is one of `on`, `standby`, `suspend` or `off`. See [displays](/features/remote-control/#displays) for what each display supports.

## Hyprland

On Hyprland, float, pin, place, resize or kill a window, move it to another workspace, run a dispatcher on the focused window, trigger a global shortcut an app registered, rename a workspace or move it to another display, switch the submap, read or set any config option, read or move the cursor, read the log, send a custom event, or reload the config:

```bash
system-bridge client hyprland set 0x555dbf21c9e0 --floating --pinned
system-bridge client hyprland set 0x555dbf21c9e0 --floating --x 100 --y 100 --width 800 --height 600
system-bridge client hyprland kill 0x555dbf21c9e0
system-bridge client hyprland move 0x555dbf21c9e0 2
system-bridge client hyprland dispatch swap_window right
system-bridge client hyprland shortcut omarchy:panel.omarchy.clock
system-bridge client hyprland workspace rename 2 Music
system-bridge client hyprland workspace move 2 HDMI-A-1
system-bridge client hyprland submap resize
system-bridge client hyprland option general.col.active_border
system-bridge client hyprland option animations.enabled false
system-bridge client hyprland cursor
system-bridge client hyprland cursor 960 540
system-bridge client hyprland log
system-bridge client hyprland event dock
system-bridge client hyprland reload
```

`set` takes `--floating` and `--pinned`, each turned off with `=false`, `--x` and `--y` to place the window, and `--width` and `--height` to size it, in pixels. `kill` ends the window's app without asking it to close. The dispatcher is one of `center_window`, `cycle_next_window`, `cycle_previous_window`, `group_next`, `group_previous`, `lock_group`, `lock_groups`, `move_focus`, `swap_window`, `toggle_group`, `toggle_split`, `unlock_group` or `unlock_groups`, and `move_focus` and `swap_window` take `down`, `left`, `right` or `up`. `--window` focuses a window first and runs the dispatcher on it. Shortcut names are in the [`desktop`](/api/data/#desktop) data's `hyprland.global_shortcuts`. `submap` with no name goes back to the default. `option` prints any config option by its name, such as `general.gaps_in` or `general:layout`, and with a value sets it until the config reloads. See [options](/api/websocket/control/#options) for the values each type takes. `cursor` prints the pointer's position, or moves it to x and y in pixels across every display.

With the `desktop.hyprlandCode` setting on, run a command through Hyprland, any dispatch written as the running config takes it, or a line of Lua with a Lua config. See [running code](/api/websocket/control/#running-code):

```bash
system-bridge client hyprland exec kitty
system-bridge client hyprland raw 'hl.dsp.focus({ workspace = "2" })'
system-bridge client hyprland eval 'hl.notification.create({ text = "Hi" })'
```

## Omarchy

While the Omarchy shell runs, open, close or toggle its menu or a panel:

```bash
system-bridge client omarchy menu open capture
system-bridge client omarchy menu close
system-bridge client omarchy panel toggle omarchy.audio
```

The action is `open`, `close` or `toggle`. Closing the menu needs no id. Menu and panel ids are in the [`desktop`](/api/data/#desktop) data's `omarchy`, and a menu also opens by one of its aliases.

## Media

Control what's playing on the backend's system:

```bash
system-bridge client media pause
system-bridge client media seek 90
system-bridge client media set_volume 0.5 --player vlc
```

The action is one of `play`, `pause`, `next`, `previous`, `stop`, `volume_up`, `volume_down` or `mute`. On Linux, it can also be `seek` with seconds, `set_volume` with 0-1, `set_shuffle` with `true` or `false`, or `set_repeat` with `none`, `track` or `list`. `--player` takes a player's `id` from the [`media`](/api/data/#media) data's `players`; without it, the action goes to the player the data describes.

## Processes

End a process by its id from the [`processes`](/api/data/#processes) data:

```bash
system-bridge client process kill 12345
system-bridge client process kill 12345 --force
```

It's asked to stop, so it can save first. `--force` ends it straight away.

## System

Switch the power profile to one of the [`system`](/api/data/#system) data's `power_profiles`:

```bash
system-bridge client system power-profile performance
```

This needs power-profiles-daemon, or tuned-ppd on Fedora. Linux only.

Keep the system from idling, for a while or until you turn it off:

```bash
system-bridge client system keep-awake on --for 2h
system-bridge client system keep-awake off
```

On Omarchy this is the bar's stay awake switch. Linux only.

## Discovery

### List Services

To list discovered services on the network, run:

```bash
system-bridge client discovery list
```

This will scan for available System Bridge instances and display them with their hostname, IP, port, and type.

## Data

### List Modules

To list all available data modules, run:

```bash
system-bridge client data list
```

By default, this outputs as a simple list. You can also use:

```bash
system-bridge client data list --json
```

To output as a JSON array.

Available flags:

- `--json`: Output as a JSON array
- `--table`: Output as a table (default)

### Run Modules

To run a specific data module and get its data as JSON, use:

```bash
system-bridge client data run --module cpu
```

For example, to get CPU data:

```bash
system-bridge client data run --module cpu
```

To run all modules and get a JSON object with all data:

```bash
system-bridge client data run --all
```

To pretty-print the JSON output:

```bash
system-bridge client data run --module cpu --pretty
```

Available flags:

- `--module` or `-m`: Module name (e.g., cpu, memory)
- `--all`: Run all modules
- `--pretty`: Pretty-print JSON output

### Watch Modules

To stream module updates from the running backend, repeat `--module` or `-m` for each module:

```bash
system-bridge client data watch --module cpu --module memory
```

The command loads the current user's API token internally and connects to the local backend. Each `DATA_UPDATE` response is written to standard output as one line of newline-delimited JSON (NDJSON). A token is never written to standard output.

The `--module` flag is required and may be repeated. Unknown module names are rejected before connecting. Stop the stream with Ctrl+C; the client closes the WebSocket normally and does not reconnect.

## History

### Export History

The backend keeps up to the last 24 hours of the readings it graphs. To export them from the running backend:

```bash
system-bridge client history export --output history.csv
```

Available flags:

- `--format` or `-f`: `csv` (the default) or `json`
- `--since` or `-s`: Only readings from this long ago, such as `1h` or `30m`
- `--module` or `-m`: Only this module's readings. Repeat it for more. History is kept for `cpu`, `memory`, `battery`, `system`, `networks`, `disks`, `gpus` and `sensors`
- `--output` or `-o`: Write to this file instead of standard output

For example, the last 6 hours of CPU and GPU readings as JSON:

```bash
system-bridge client history export --module cpu --module gpus --since 6h --format json
```

The CSV has a row per reading with the columns `time`, `metric`, `id`, `value` and `unit`. Times are in UTC, and `id` names the GPU, disk, sensor or fan for the readings that have one. The JSON is the history as the [`GET_HISTORY`](/api/websocket/data/#getting-history) event returns it. The web client has the same export in the Export menu on the overview and on each module's page. It lists every module with history as a checkbox, ticked to start for the modules that page graphs: all of them on the overview, and the page's own module elsewhere, plus the CPU and GPUs on the System page, whose power graph shows theirs too. The TypeScript and Python connectors can write the same CSV.

## Diagnostics

To see how the running backend is doing, for a bug report:

```bash
system-bridge client diagnostics
```

It prints the [`GET_DIAGNOSTICS`](/api/websocket/data/#getting-diagnostics) reply as indented JSON: the version, platform, when the backend started, each data module's failures and last error, a summary of the settings and up to the last 20 warnings and errors. Your home directory shows as `~` and your user name as `<user>`, so it's safe to share.

## Backend

To run the backend server, use:

```bash
system-bridge backend
```

Add `--open-web-client` to open the [web client](/using/web-client/) once the backend has started:

```bash
system-bridge backend --open-web-client
```

See [Running](/running/) for autostart and service setup.

## Version

To get the version of System Bridge, run:

```bash
system-bridge version
```

## Completions

System Bridge can generate shell completion scripts for the CLI, so you get tab-completion of commands, flags and data module names.

On Linux, the DEB, RPM and Arch packages install completions for bash, zsh and fish automatically. Start a new shell after installing and completion works with no extra setup.

To enable completions yourself, or on another shell, generate a script with:

```bash
system-bridge completions <shell>
```

Supported shells are `bash`, `zsh`, `fish` and `pwsh` (PowerShell). Source the output to load completion into your shell:

```bash
# bash (~/.bashrc)
source <(system-bridge completions bash)

# zsh (~/.zshrc)
source <(system-bridge completions zsh)

# fish
system-bridge completions fish > ~/.config/fish/completions/system-bridge.fish
```

On PowerShell, load it in the current session, and add the same line to your profile to make it persist:

```powershell
system-bridge completions pwsh | Out-String | Invoke-Expression
```

:::tip
Completion is aware of your data modules. Once it is enabled, type `system-bridge client data run --module` followed by a space and press Tab to complete with the available module names.
:::

## Next steps

- Prefer a graphical interface? Use the [web client](/using/web-client/).
- Connect to the [API and WebSocket](/api/) to read data and control your system.
- Integrate with [Home Assistant](/using/home-assistant/).
- Not started the backend yet? See [Running](/running/).