Use ObConf to preview, archive and install Openbox themes

You will finish with a safe way to launch ObConf, point it at a particular Openbox configuration, create a theme archive, and install an existing .obt archive. The examples use ObConf from package version 1:2.0.4+git20150213-3build1, installed on an Ubuntu system.

Allow about fifteen minutes. You need a running graphical Openbox session for the preferences window. You do not need root for the normal commands. This guide does not edit system files, replace a window manager or install a theme without warning.

1. Check the installed command

Confirm the package and executable before opening a graphical tool. These are ordinary, read-only commands:

$ dpkg-query -W -f='${Package} ${Version}\n' obconf
obconf 1:2.0.4+git20150213-3build1
$ command -v obconf
/usr/bin/obconf

The local manual describes ObConf as a preferences manager for Openbox version 3.0 and later. Its documented syntax is obconf [OPTIONS] [ARCHIVE.obt]. The optional archive argument is not a general file picker: it is an Openbox theme archive that ObConf can open as part of its graphical workflow.

Checkpoint: if command -v obconf prints nothing, stop and install the distribution package through your normal software-management process. Do not copy a binary into /usr/bin by hand.

2. Open ObConf in the graphical session

Run this as the desktop user whose Openbox settings you want to change:

$ obconf

The window should open with ObConf's preferences tabs. If you run the command from a text-only console, a remote shell without display forwarding, or a service account, GTK may report that it cannot open the display. That is an environment problem, not evidence that the package is missing.

Do not use sudo obconf to work around a display error. It can make the root account own files created by the GUI and can apply changes to the wrong user's Openbox configuration. Start the command inside the intended graphical login instead.

ObConf also documents --version. Run it in the graphical session if you want the program's own version display:

$ obconf --version

This binary initialises GTK before it exits. Without a display it can print a GTK warning and return a non-zero status before showing the version, so use dpkg-query above when you need an unambiguous package version from a shell.

3. Select the configuration file deliberately

Use --config-file when you need ObConf to work with a particular Openbox configuration file. First check that the path exists:

$ CONFIG_FILE="$HOME/.config/openbox/rc.xml"
$ test -r "$CONFIG_FILE" && echo "readable: $CONFIG_FILE"
readable: /home/you/.config/openbox/rc.xml
$ obconf --config-file "$CONFIG_FILE"

Replace /home/you with the real home directory, or leave the variable unset and use the path printed by your own shell. The command above assumes a per-user configuration. A system-wide example is /etc/xdg/openbox/rc.xml, but do not edit or overwrite it casually. If you need to change a file owned by root, inspect it first and make a backup; elevated privileges are only for the specific file operation that requires them.

Checkpoint: after the window opens, confirm that you are looking at the intended user's Openbox settings before pressing an Apply or Save control. If the file is missing, create or select the configuration through your normal Openbox setup rather than guessing a replacement path.

4. Create an archive from a theme directory

The --archive option creates a theme archive from a supplied theme directory. Use a directory containing the Openbox theme files, not the parent directory containing many unrelated themes. For example, the installed theme data normally ends in an openbox-3 directory:

$ THEME_DIR="/path/to/MyTheme/openbox-3"
$ test -d "$THEME_DIR" && echo "theme directory found"
theme directory found
$ obconf --archive "$THEME_DIR"

ObConf then uses its graphical interface and the archive workflow to create an .obt file. The output location and any confirmation prompts are controlled by this version's GUI, so do not script around an invented filename or default directory. Check the file manager or chooser after the operation and verify that the archive is non-empty before copying it elsewhere:

$ stat -c '%n %s bytes' "/path/to/MyTheme.obt"
/path/to/MyTheme.obt 12345 bytes

The number is only an example. Keep the original theme directory until you have tested the archive. If the archive is wrong, remove only the newly created .obt file after checking its exact path. Do not delete the source theme directory as a shortcut.

5. Install an archive and keep a recovery path

--install installs a supplied archive and selects it. This changes the desktop user's Openbox theme, so treat it as a configuration change rather than a read-only test:

$ ARCHIVE="/path/to/MyTheme.obt"
$ test -r "$ARCHIVE" && stat -c '%n %s bytes' "$ARCHIVE"
/path/to/MyTheme.obt 12345 bytes
$ obconf --install "$ARCHIVE"

Do not run this against an archive downloaded from an untrusted source. An archive is input to a desktop configuration tool, and a theme can affect how your session looks and behaves. Keep a copy of the previous theme archive or record its name before installing the new one.

There is no documented command-line undo option. To recover, reopen ObConf, select the previous theme in the theme controls and apply it again. If the GUI cannot start after a bad selection, return to the graphical session with the old archive available and restore the user's Openbox configuration from the backup you made before the change. Do not delete the entire Openbox configuration directory while troubleshooting.

6. Use the remaining options only when needed

--tab NUMBER asks ObConf to display a particular tab. The manual does not define a stable name-to-number mapping, so use it only when you have confirmed the number for this build. A normal launch is easier to diagnose:

$ obconf
$ printf 'exit status: %s\n' "$?"
exit status: 0

A zero exit status means the process completed; it does not prove that a theme was selected or that a display change took effect. Verify the result in the ObConf window and, if necessary, restart or reload Openbox using the method documented by your desktop setup. Avoid restarting the window manager during work that depends on the current session unless you have saved your work.