CLI

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:

system-bridge client token

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:

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:

system-bridge client open

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

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

Quit

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

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:

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 data. Use --mute to mute it and --default to make it the default output or input. See audio for what each platform supports.

Bluetooth

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

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 data. See Bluetooth for what each platform supports.

Clipboard

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

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 on your list and the prefabs, and run one by its ID:

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:

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 ids from the desktop data. state takes --fullscreen, --maximised and --minimised, each turned off with =false. See desktop for what each desktop supports.

Discord

Control Discord voice, once Discord is set up:

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:

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

The id is the display’s id from the displays data. The power state is one of on, standby, suspend or off. See 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:

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

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:

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 data’s omarchy, and a menu also opens by one of its aliases.

Media

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

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 data’s players; without it, the action goes to the player the data describes.

Processes

End a process by its id from the processes data:

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 data’s power_profiles:

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:

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:

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:

system-bridge client data list

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

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:

system-bridge client data run --module cpu

For example, to get CPU data:

system-bridge client data run --module cpu

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

system-bridge client data run --all

To pretty-print the JSON output:

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:

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:

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:

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

system-bridge client diagnostics

It prints the GET_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:

system-bridge backend

Add --open-web-client to open the web client once the backend has started:

system-bridge backend --open-web-client

See Running for autostart and service setup.

Version

To get the version of System Bridge, run:

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:

system-bridge completions <shell>

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

# 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:

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

Next steps

• Prefer a graphical interface? Use the web client.
• Connect to the API and WebSocket to read data and control your system.
• Integrate with Home Assistant.
• Not started the backend yet? See Running.