Getting Started¶

With oxbow, oxctl, and river installed you are ready to begin configuration.

Attention

Please see river’s list of useful software for additional tools (launcher, bar, lock screen, wallpaper).

Init configuration¶

oxbow runs the init script at ~/.config/oxbow/init on startup.

opam

Create ~/.config/oxbow/init script:

#!/bin/sh
eval "$(opam env)"
oxctl bind spawn foot to Super+Return

Make the script executable:

chmod +x ~/.config/oxbow/init

NixOS

Extend the module from NixOS River setup:

{ pkgs, ... }:
let
  oxctl = "${pkgs.oxbow}/bin/oxctl";
  oxbow-init = pkgs.writeShellScript "oxbow-init" ''
    ${oxctl} bind spawn foot to Super+Return
  '';
  river-init = pkgs.writeShellScript "river-init" ''
    exec ${pkgs.oxbow}/bin/oxbow -c ${oxbow-init}
  '';
  wrapped-river = pkgs.symlinkJoin {
    name = "river";
    paths = [ pkgs.river ];
    nativeBuildInputs = [ pkgs.makeWrapper ];
    postBuild = ''
      wrapProgram $out/bin/river --add-flags "-c ${river-init}"
    '';
  };
in
{
  environment.systemPackages = [ wrapped-river ];
}

Attention

oxbow -c overrides ~/.config/oxbow/init. Use one or the other.

Home Manager

Add the following module to your configuration:

{ pkgs, ... }:
let
  oxctl = "${pkgs.oxbow}/bin/oxctl";
in
{
  xdg.configFile = {
    "oxbow/init" = {
      executable = true;
      text = ''
        #!/bin/sh
        ${oxctl} bind spawn foot to Super+Return
      '';
    };
  };
}

First launch¶

Start river; oxbow starts with it and runs the init script.

These keybinds are enough for a first session.

Keybind	Action
`Super+Return`	Spawn the foot terminal
`Super+j`	Focus the next window in the stack
`Super+k`	Focus the previous window in the stack
`Super+q`	Close the focused window
`Super+Q`	Exit the Wayland session and return to greeter or TTY

See the defaults here for the full list.

Settings¶

Open up foot and run the following commands:

oxctl gaps inner 0
oxctl gaps outer 0

Configure the borders as well:

oxctl border width 2
oxctl border color focused '#bb9af7'
oxctl border color unfocused '#71799d'
oxctl border color urgent '#f7768e'

Configure input devices:

oxctl input pointer follow always
oxctl input pointer warp on
oxctl input keyboard repeat 50 250

See the oxctl reference here for the keybind syntax.

Tags¶

Move windows between tags:

oxctl window tag set 2

View multiple tags at once:

oxctl tag view 1,2

Layouts¶

oxbow has three layouts:

Tiling: Super+t
Scrolling: Super+s
Floating: Super+f

Tiling¶

The tiling layout works like dwm. One master window on the left, the rest stacked evenly on the right. Open five windows then change the orientation, and stacking arrangement:

oxctl layout tiling orientation right
oxctl layout tiling spiral

Switch back to the default:

oxctl layout tiling orientation left
oxctl layout tiling even

See all the arrangements here.

Scrolling¶

Switch to the scrolling layout with Super+s. There are three alignments: Visible, Left, and Centered:

Visible

The visible alignment will only rescroll when focusing a column that is not fully visible.

oxctl layout scrolling visible

When column B is focused, changing focus to column C will scroll the strip so that C’s right border is aligned with the right side of the output.

Left

The left alignment puts the left edge of the focused column on the left edge of the output.

oxctl layout scrolling left

Centered

The centered alignment keeps the focused column in the center of the output.

oxctl layout scrolling centered

The scrolling layout can also scroll vertically. See scrolling orientation in the reference.

Floating¶

In the floating layout, oxbow does not tile windows. Windows keep the position and size that you give them.

Overview¶

Overview shows all visible windows and cycles focus through them, like alt-tab. Test it with these binds:

oxctl bind output overview cycle next --until-release=Super to Super+n
oxctl bind output overview cycle prev --until-release=Super to Super+Shift+n

Hold Super and press n to cycle. Release Super to select the focused window.

The overview looks like this:

When there are more than six windows on an output, the grid scrolls vertically. Continue pressing Super+n to scroll to offscreen windows.

Note

The overview is displayed in focus order.

Multiple outputs¶

List the output names with:

oxctl output list

Output focus¶

Focus a specific output with:

oxctl output focus match --name HDMI-A-1
oxctl output focus match --name DP-1

Focus an output spatially with:

oxctl output focus left
oxctl output focus right
oxctl output focus up
oxctl output focus down

Tag swaps¶

Swap a set of tags between outputs:

oxctl bind output swap tags --ring HDMI-A-1,DP-3,DP-1 to Super+e
oxctl bind output swap tags --ring HDMI-A-1,DP-3,DP-1 --rev to Super+w

Each press swaps the focused output’s windows with the next output in the ring. For example, start with these windows on tag 1:

Output	Windows
`HDMI-A-1`	F
`DP-3`	A, B
`DP-1`	C, D, E

Focus DP-3 and press Super+e. DP-3 now has C, D, and E. DP-1 has A and B.
Press Super+e again. All windows are back where they started.
Focus HDMI-A-1 and press Super+w. HDMI-A-1 has C, D, and E. DP-1 now has F.

Window rules¶

Add rules to windows with:

oxctl window rules add --tags 3 --output=DP-3 --app-id=firefox
oxctl window rules add --tags 2 --output=DP-3 --app-id=emacs
oxctl window rules add --tags 9 --app-id=org.keepassxc.KeePassXC
oxctl window rules add --tags 4 --output=DP-3 --app-id=steam

These rules set the initial tags and output for each window matching the given app-id.

View existing rules:

oxctl window rules list
INDEX  PATTERN                                        EFFECTS
0      app_id=firefox case=sensitive                  output=name=DP-3 policy=keep tags=concrete 4
1      app_id=emacs case=sensitive                    output=name=DP-3 policy=keep tags=concrete 2
2      app_id=org.keepassxc.KeePassXC case=sensitive  tags=concrete 256
3      app_id=steam case=sensitive                    output=name=DP-3 policy=keep tags=concrete 8

Delete rules

oxctl window rules remove 0,2
oxctl window rules list
INDEX  PATTERN                                        EFFECTS
0      app_id=emacs case=sensitive                    output=name=DP-3 policy=keep tags=concrete 2
1      app_id=steam case=sensitive                    output=name=DP-3 policy=keep tags=concrete 8

Rules can also define the position and dimension of windows. Matching can also be done on a window’s title with --title. --app-id and --title are regular expressions. See the reference for the full set of window rules.

Go deeper¶

oxctl can also query the state of windows, tags, and outputs. It can subscribe to events for scripts and status bars. See:

Note

Pass --help to any oxctl command to see its subcommands and options.