Command Syntax Rewrite

Dino Hensen edited this page Mar 21, 2016 · 16 revisions

Here is a new spec (iteration number 5). It assumes that you meant that you really don't care about compatibility.

The main concept is the selection language and the flipping of commands. Objects (windows, desktops, and monitors) can be selected by using a reserved word, using a reserved word along with a class, or by directly specifying the object's name or id. For example, the next free desktop would be specified as while the monitor named 'Two' would simply be Two. Unfortunately, this means that no object may be named a reserved word or prefixed with a reserved word followed by a dot (<reserved>.*).

The commands are reversed when compared to the previous syntax. That is, the main command groups what is being acted on and the flags specify what actions should be taken. For me at least, this feels a lot more natural and useful (can specify multiple actions).

The reserved words are: left, right, up, down, next, prev, last, biggest, focused.

The main thing I don't like is the whole "class" system. Unfortunately, I can't think of a better way to do this. I can't use flags as the order/location of flags really shouldn't be important.

I apologize if anything is unclear/missing.

Note: the [*_SEL] prefixing actions allows the user to override the "current" window. Technically, window -f SEL and window SEL -f are equivalent but the second is more readable.


DESKTOP_CLASS   := [occupied|free]
WINDOW_CLASS    := [floating|tiled][like|unlike]
DIR             := left|right|up|down
CYCLE           := next|prev
ROTATE          := clockwise|counter_clockwise|full_cycle
FLIP            := horizontal|vertical

WINDOW_SEL      := (CYCLE|DIR|biggest|focused|last)[.WINDOW_CLASS] | <window_id>
DESKTOP_SEL     := (CYCLE|focused|last)[.DESKTOP_CLASS] | <desktop_name>
MONITOR_SEL     := (CYCLE|DIR|focused|last)[.DESKTOP_CLASS] | <monitor_name>


Window Command

Window commands act on a single window. Flags can be arbitrarily combined (within reason).


window  [WINDOW_SEL]    --focus|-f          [WINDOW_SEL]
                        --to-desktop|-d     DESKTOP_SEL
                        --to-monitor|-m     MONITOR_SEL
                        // Transplant window and adjust tree.
                        // Keep?
                        --to-window|-w      WINDOW_SEL
                        // Swaps unless presel set on either window. If presel
                        // is set, it "absorbs" the swap. This might get
                        // confusing.
                        --swap|-s           WINDOW_SEL
                        --toggle|-t         visibility[=on|off]
                            // Short flag?
                        --presel|-p         DIR|cancel
                            // Sets the ratio. Can be combined with --presel
                        --ratio|-r          RATIO
                        --edge|-e           DIR RATIO|pull|push


  • Move window to the previous desktop and follow (focus): window -d prev -f
  • Move window to the left monitor and make it full screen: window -m left -t fullscreen=on
  • Swap the focused window with the one on the left: window -s left
  • Horizontally split the focused window above the window to the right (requires change: moving preseled window into another activates the presel): window -f -p down -s right
  • Focus the last focused window: window -f last
  • Focus the next floating window of the same class: window -f
  • Equivalent of pull left: window --edge left pull.
  • Equivalent of presel right .1: window --presel right --ratio .1.
  • Equivalent of fence_ratio right .3: window --edge right .3.
  • Equivalent of ratio .6: window --ratio .6.

Query Command

Returns a reasonable representation of the intersection of the requested type and target.

Note: --history and --tree are nonsensical when combined with --window


query   [--monitor|-m [MONITOR_SEL]  |  --desktop|-d [DESKTOP_SEL]  |  --window|-w [WINDOW_SEL]] \
            --windows|-W        // List matching windows
            --desktops|-D       // List matching desktops
            --monitors|-M       // List matching monitors
            --tree|-T           // Print tree rooted at query
            --history|-H        // Print the history as it relates to the query


Command Returns
-W all windows
-W -m all windows on the current monitor
-W -m M all windows on M
-W -d all windows on the current desktop
-W -d D all windows on D
-W -w id of the focused window (if any)
-W -w W id of W (if it exists)
-D all desktops (Also lists containing monitors)
-D -m desktops on the current monitor
-D -m M desktops on M
-D -d name of the focused desktop
-D -d D name of D (if it exists)
-D -w the desktop containing the focused window
-D -w W the desktop containing window W
-M all monitors
-M -d the monitor containing the current desktop
-M -d D the monitor containing D
-M -m the name of the current monitor
-M -m M the name of M
-M -w the name of the monitor containing the focused window
-M -w W the name of the monitor containing W
-T the entire tree
-T -m the tree rooted at the focused monitor
-T -m M the tree rooted at M
-T -d the tree rooted at the focused desktop
-T -d D the tree rooted at D
-T -w [W] nonsensical/does window W exist in the tree?
-H the window history across all monitors/desktops
-H -m the window history for the current monitor
-H -m M the window history for M
-H -d the window history for the current desktop
-H -d D the window history for D
-H -w [W] nonsensical / Could give the monitor/desktop history of a window


  • All windows: query -W
  • The desktop containing the requested window: query -D -w 0xID
  • The focus history for desktop 'One': query -H -d One
  • Does desktop 'One' exist: query -D -d One
  • Monitors containing desktop 'Two': query -M -d Two
  • Windows contained in desktop 'Two': query -W -d Two

Desktop Command

Perform actions on a single desktop (defaults to current).


desktop [DESKTOP_SEL]   --focus|-f          [DESKTOP_SEL]
                        --to-monitor|-m     MONITOR_SEL
                        --layout|-l         CYCLE|LAYOUT
                        --rename|-n         <new_name>
                        --flip|-F           FLIP
                        --rotate|-R         ROTATE
                        --circulate|-C      forward|backward


  • Remove the current desktop and focus the next one: desktop -r -f next.
  • Flip and balance the current desktop: desktop -F -B
  • Focus the next free desktop: desktop -f

Monitor Command

Act on a single monitor. Doesn't do much.

monitor [MONITOR_SEL]   --focus|-f           [MONITOR_SEL]
                        --add-desktops|-a    <name>...
                        --remove-desktops|-r [<name>...]
                        --pad|-p             PADDING...
                        --rename|-n          <new_name>


  • Remove all desktops on a monitor: monitor -r

Restore Command

Used to restore saved state (can be saved by making the appropriate queries.


restore --history|-H            FILE_PATH
        --tree|-T               FILE_PATH // Equivalent to restore_layout but
                                          // doesn't re-use the term 'layout'.

Control Command

Miscellaneous control commands (anything goes).


control --adopt-orphans | --put-status | --reset-desktops

Quit Command

While this could have gone under control, it might be important enough to deserve it's own command.


quit    [<status>]

Rule Command

Control rules. Instead of using rule-specific window modification logic, arbitrary window flags can be applied to the window.


rule    --add|-a                <pattern>       ANY_OF_THE_WINDOW_FLAGS...
        --rm|-r                 <rule_uids>...
        --list|-l               [<pattern>]


  • Adblock (joking): rule -a "Annoying Advert" -c
  • Open Pithos (pandora) in background desktop (locked): rule -a "Pithos" -d -t locked=on

Pointer Command

Control pointer grabbing


pointer --track|-t <x> <y>
        --grab|-g [focus|move|resize_side|resize_corner]

Config Command

Shamelessly ripped from git.


config  [--unset|-u]               key [value]


Current New
list [DESKTOP_NAME] query -T -d [DESKTOP_NAME]
list_desktops query -T -m
list_monitors query -T
list_desktops --quiet query -D -m
list_monitors --quiet query -M
list_history query -H -m
list_windows query -W
list_rules rule --list
presel DIR window -p DIR
presel DIR RATIO window -p DIR -r RATIO
cancel window -p cancel
cancel --all desktop --cancel-presel
ratio VALUE window -r VALUE
pad MONITOR_NAME ... monitor MONITOR_NAME --pad ...
focus DIR window -f DIR
shift DIR window -s DIR -f
swap --keep-focus window -s last
swap window -s last -f last
push DIR window -e DIR push
pull DIR window -e DIR pull
fence_ratio DIR RATIO window -e DIR RATIO
cycle next|prev [...] window -f (next|prev)[.classes]
biggest query -W -w biggest
circulate forward|backward desktop -C forward|backward
grab_pointer ... pointer --grab ...
track_pointer ... pointer --track ...
toggle_* window -t *
toggle_visibility bspc query -W | xargs -n1 bspc window {} -t visibility
close window -c
kill window -k
send_to DESKTOP [--follow] window -d DESKTOP [-f]
drop_to CYCLE [--follow] window -d CYCLE [-f]
send_to_monitor MONITOR [--follow] window -m MONITOR [-f]
drop_to_monitor CYCLE [--follow] window -m CYCLE [-f]
use DESKTOP desktop -f DESKTOP
use_monitor MONITOR monitor -f MONITOR
focus_monitor DIR monitor -f DIR
alternate window -f last
alternate_desktop desktop -f last
alternate_monitor monitor -f last
add DESKTOP_NAME... monitor -a DESKTOP_NAME...
remove_desktop DESKTOP_NAME... monitor -r DESKTOP_NAME...
send_desktop_to MONITOR [--follow] desktop -m MONITOR [-f]
cycle_monitor CYCLE monitor -f CYCLE
cycle_desktop CYCLE [...] desktop -f CYCLE[.classes]
layout LAYOUT [DESKTOP_NAME] desktop [DESKTOP_NAME] layout
layout LAYOUT [DESKTOP_NAME ...] bspc query -D | xargs -n1 bspc desktop {} -l LAYOUT
cycle_layout desktop -l next
rotate ROTATION desktop -R ROTATION
flip FLIP_DIR desktop -F FLIP_DIR
balance desktop -B
rule PATTERN floating rule -a PATTERN -t floating=on
rule PATTERN follow rule -a PATTERN -t follow=on
remove_rule UID ... rule -r UID ...
put_status control --put-status
adopt_orphans control --adopt-orphans
restore_layout FILE restore --layout FILE
restore history FILE restore --history FILE
quit [EXIT] quit [EXIT]
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.