Command Line

ionwl

This runs the compositor. It is configured through the Python config file (see Configuration), so the command line stays minimal.

Usage: ionwl [OPTIONS]

IonWL - a tiling Wayland compositor configured in Python.

IonWL is configured through the Python config file at
~/.config/ionwl/ion_init.py; the command line takes only the options below.

Options:
  -h, --help           Print this help message
  --config-dir <PATH>  Use PATH as the config directory

Environment variables:
  RUST_LOG                Log filter, e.g. ionwl=debug (default: ionwl=info)
  NO_COLOR                Disable colored log output
  IONWL_BACKEND           Force the backend: winit, udev or headless
                          (default: auto-detect from WAYLAND_DISPLAY / DISPLAY;
                          headless is never detected, only asked for)
  IONWL_HEADLESS_SIZE     Output size of the headless backend as WIDTHxHEIGHT
                          (default: 1920x1080)
  IONWL_TIMING            Enable render and operator timing probes
  IONWL_NO_RENDER_THREAD  Use the inline render path instead of per-output
                          render threads (DRM/KMS backend)
  IONWL_NOTIFY_COMMAND    Program run to show desktop notifications
                          (default: notify-send)

ionwl-cmd

This communicates with the running compositor over its IPC socket.

Only the user running the compositor can connect to the socket, and a process running as anyone else is refused. The Python sent over it runs inside the compositor with its full authority, just as the config does, so access to the socket is equivalent to editing the config and reloading it.

Commands run on the compositor’s main loop, with no time limit. One that does not return, such as an endless loop, a time.sleep or a subprocess.run waiting on its child, freezes the session until it does. Start long-running work with ion.utils.exec() or ion.utils.shell() rather than waiting on it.

The primary way to perform tasks is by executing Python.

Usage: ionwl-cmd [OPTIONS] <COMMAND> ...

ionwl-cmd - send commands to a running IonWL compositor over its IPC socket.

Check status or execute Python inside the compositor - useful for scripts and
for keybindings bound to external tools.

Commands:
  ping           Check the compositor is running
  python-eval    Evaluate a Python expression, print result
  python-exec    Execute Python code
  python-file    Execute a Python file

Options:
  -h, --help     Print this help message
  -V, --version  Print the version

Run 'ionwl-cmd <COMMAND> --help' for the options of a command.

Environment:
  The compositor is located via XDG_RUNTIME_DIR and WAYLAND_DISPLAY; run
  ionwl-cmd from the same environment as the compositor.

Examples:
  ionwl-cmd ping
  ionwl-cmd python-eval '1 + 1'
  ionwl-cmd python-eval 'int(ion.app.ipc_args[0]) + 1' -- 41
  ionwl-cmd python-exec 'print("hello")'
  ionwl-cmd python-exec 'ion.wm.window_close()'
  ionwl-cmd python-exec 'ion.ops.compositor_logout().call(ion.types.EventCommand())'
  ionwl-cmd python-file ~/scripts/setup.py
  ionwl-cmd python-file script.py -- /tmp/data.json

Each command has options of its own, which follow it on the command line.

ping

Usage: ionwl-cmd ping [OPTIONS]

Check the compositor is running.
Exit code is 0 on success, otherwise 1.

Options:
  -h, --help  Print this help message

python-eval

Usage: ionwl-cmd python-eval [OPTIONS] <EXPRESSION> [-- <ARG> ...]

Evaluate a Python expression, print result

Arguments:
  <EXPRESSION>          The expression to evaluate

Options:
  -h, --help            Print this help message
  --import <MOD1:MOD2>  Import modules before running the Python code
                        (default: ion; pass --import= with no modules for none)
  --no-output-redirect  Don't redirect Python stdout/stderr back to the client
                        (by default, print() output is captured and returned)
  -- <ARG> ...          Expose the remaining arguments to the Python code
                        as ion.app.ipc_args

python-exec

Usage: ionwl-cmd python-exec [OPTIONS] <CODE> [-- <ARG> ...]

Execute Python code

Arguments:
  <CODE>                The code to execute

Options:
  -h, --help            Print this help message
  --import <MOD1:MOD2>  Import modules before running the Python code
                        (default: ion; pass --import= with no modules for none)
  --no-output-redirect  Don't redirect Python stdout/stderr back to the client
                        (by default, print() output is captured and returned)
  -- <ARG> ...          Expose the remaining arguments to the Python code
                        as ion.app.ipc_args

python-file

Usage: ionwl-cmd python-file [OPTIONS] <PATH> [-- <ARG> ...]

Execute a Python file

Arguments:
  <PATH>                The file to execute

Options:
  -h, --help            Print this help message
  --import <MOD1:MOD2>  Import modules before running the Python code
                        (default: none)
  --no-output-redirect  Don't redirect Python stdout/stderr back to the client
                        (by default, print() output is captured and returned)
  -- <ARG> ...          Expose the remaining arguments to the Python code
                        as ion.app.ipc_args