Skip to content

qtile shell

The Qtile command shell is a command-line shell interface that provides access to the full complement of Qtile command functions. The shell features command name completion, and full command documentation can be accessed from the shell itself. The shell uses GNU Readline when it's available, so the interface can be configured to, for example, obey VI keybindings with an appropriate .inputrc file. See the GNU Readline documentation for more information.

The shell presents a filesystem-like interface to the command graph - the builtin "cd" and "ls" commands act like their familiar shell counterparts:

> ls
layout/  widget/  screen/  bar/     window/  group/

> cd screen
layout/  window/  bar/  widget/

> cd ..
/

> ls
layout/  widget/  screen/  bar/     window/  group/

If you try to access an object that has no "default" value then you will see an error message:

> ls
layout/  widget/  screen/  bar/     window/  group/

> cd bar
Item required for bar

> ls bar
bar[bottom]/

> cd bar/bottom
bar['bottom']> ls
screen/  widget/

Please refer to Navigating the command graph for a summary of which objects need a specified selector and the type of selector required. Using ls will show which selectors are available for an object. Please see below for an explanation about how Qtile displays shell paths.

Alternatively, the items() command can be run on the parent object to show which selectors are available. The first value shows whether a selector is optional (False means that a selector is required) and the second value is a list of selectors:

> ls
layout/  widget/  screen/  bar/     window/  group/

> items(bar)
(False, ['bottom'])

Displaying the shell path

Note that the shell provides a "short-hand" for specifying node keys (as opposed to children). The following is a valid shell path:

> cd group/4/window/31457314

The command prompt will, however, always display the Python node path that should be used in scripts and key bindings:

group['4'].window[31457314]>

Live Documentation

The shell help command provides the canonical documentation for the Qtile API:

> cd layout/1

layout[1]> help
help command   -- Help for a specific command.

Builtins
========
cd    exit  help  ls    q     quit

Commands for this object
========================
add           commands      current       delete        doc
down          get_info      items         next          previous
rotate        shuffle_down  shuffle_up    toggle_split  up

layout[1]> help previous
previous()
Focus previous stack.