// OPENBOX DOCS

Command line and deep links

Launch OpenBox from a terminal, script backups, and drive the app with openbox:// deep links.

Command line and deep links

OpenBox is a local app, so the command line is a first-class surface. This page covers every flag the app entry point accepts and the openbox:// URI scheme you can use to drive a running instance.

Entry points

CommandWhat it starts
openboxThe native window (default)
openbox-nativeThe native window (the same host)
openbox --webThe loopback web UI in a browser (development)

The native window renders the same UI as the web fallback; both serve index.html over the loopback server. Flags below apply to the app entry point unless noted.

Flags

FlagBehavior
-h, --helpShow command-line options and usage summary, then exit.
--bigboxOpen the UI straight into Big Box mode at startup by appending &deeplink=bigbox to the launch URL. Ignored by --backup/--restore-backup, which never start the server. (v1.14.0+)
--no-browserStart the server without opening a window. Useful for remote or scripted starts; the printed URL still works.
--game-modeForce gamescope guest behavior (Steam Deck / Bazzite Game Mode). On the web entry point this opens Big Box fullscreen in a kiosk browser; the native window detects gamescope guests from the environment and needs no flag.
--bigboxOpen the UI with ?deeplink=bigbox so it starts in Big Box mode. Pairs with the Start in Big Box mode setting (bigbox_start_at_launch) for Deck/HTPC boot.
--play <id>Launch a game by stable game_id or numeric library id, using the authenticated local launch route. This is the command used by Steam Bridge shortcuts.
--uri <openbox://...>Dispatch a deep link against a running instance (or start one) and exit. You can also pass a bare openbox://... URI directly as a positional argument.
--launcherOpen the rofi/wofi/dmenu keyboard launcher against the running instance and exit.
--backup [--items a,b] [--keep N]Create a library backup from the command line. Default items are library,settings. Prints the archive path.
--restore-backup <archive>Restore a backup archive. The archive must be a real .zip inside the data directory or backups/. Prints the restored item names.
--webStart the loopback web UI in a browser instead of the native window (development).
--app-windowWeb entry point only: open the UI in a chrome-less app window (browser --app= mode) instead of a normal tab. The native window is unaffected.
--no-app-windowWeb entry point only: open the UI in a normal browser window; overrides the chrome-less app window default there. The native window is unaffected.
--fullscreen-width <W> / --width <W>Web entry point: customize the viewport width in kiosk and app window modes.
--fullscreen-height <H> / --height <H>Web entry point: customize the viewport height in kiosk and app window modes.
--resolution <WxH> / --resolution=<WxH>Web entry point: customize the viewport resolution (e.g. --resolution 1920x1080).

--backup and --restore-backup act on the library before the server starts, so they work even when no instance is running. They read OPENBOX_DATA_DIR from the environment, like every startup path.

openbox:// URIs address a running OpenBox instance. The parser rejects foreign hosts and fails cleanly when no server port is known, so a dead link never silently hits the wrong process.

URIAction
openbox://startOpen the running UI in the browser. A no-op if the server is already up.
openbox://search/<query>Open the UI with the search field prefilled for <query>.
openbox://showgame/<id> (alias game)Open the detail pane for a game by numeric or stable id.
openbox://launch/<id>Launch a game by numeric or stable id. openbox --play <id> uses this launch action.
openbox://resume/<id>Resume a stored Quick Resume state for a game by numeric or stable id. The adapter must expose a compatible state and the stored state must not be stale unless the caller explicitly allows it through the API.
openbox://moment/<id>Open a Moment deep link for its id in the running UI.
openbox://clip/<id>Open a Record That clip deep link for its id in the running UI.
openbox://bigbox (alias fullscreen)Switch the running UI to Big Box mode.
openbox://settings[/<panel>]Open Settings. A panel segment is parsed but not currently routed to a specific settings tab.

Arcade Room is opened from Tools → Arcade Room or the Ctrl/Cmd-K command palette. The current URI parser and SPA do not register an openbox://arcade action, so do not substitute an unregistered URI for that UI entry point.

Usage:

openbox --uri "openbox://search/chrono"
openbox --play "GAME_ID"
openbox --uri "openbox://resume/GAME_ID"
openbox --uri "openbox://moment/MOMENT_ID"
openbox --uri "openbox://clip/CLIP_ID"

--uri dispatches against the running server using the token and port files, or boots a server if none is running. The browser-facing actions currently wired by the SPA include ?deeplink=bigbox, ?deeplink=search&q=chrono, ?deeplink=showgame&id=GAME_ID, ?deeplink=moment&id=MOMENT_ID, and ?deeplink=clip&id=CLIP_ID. Resume is dispatched by the URI/CLI path to the authenticated API; Arcade Room remains a Tools/palette action.

Keyboard launcher

openbox --launcher (or scripts/openbox-launcher.sh) opens a rofi, wofi, or dmenu picker against the running instance. It queries /api/launcher/menu, which lists Big Box, Settings, Search, and up to 40 games. Selecting an entry dispatches it.

# picker auto-detected (rofi > wofi > dmenu)
openbox --launcher

# or run the helper directly with a specific picker
scripts/openbox-launcher.sh rofi

The launcher reads server.port and server.token from the data directory, so it only works while OpenBox is running. Bind a hotkey to openbox --launcher for a launch-anything menu.