Skip to content

i3king

Jump to bottom
budRich edited this page Jul 13, 2023 · 12 revisions

NAME

i3king - window ruler

SYNOPSIS

i3king [OPTIONS]

OPTIONS

-a, --apply                | Match all existing windows against the rules and exit.
-c, --config         FILE  | use FILE as config  
-n, --conid          CONID | window with CONID, match against rules and exit exit.
--dryrun                   | Parse rules but don't execute commands.
-h, --help                 | print help and exit  
--json               JSON  | use JSON instead of output from: `i3-msg -t subscribe`
--log                FILE  | print messages to FILE instead of STDERR  
--no-apply                 | dont re-apply the rules on i3 crash 
--no-restart               | dont restart on i3 crash  
--print-commands           | Print commands to STDOUT instead of executing them.
--reload                   | force reload of i3king  
--verbose                  | More verbose output to **STDERR**.  
-v, --version              | print version info and exit  
-d, --winid          WINID | window with WINID, match against rules and exit exit.

-c, --config FILE

Override the value of the Environment variable I3_KING_RULE_FILE . Or the default value:
~/.config/i3king/rules

--no-apply

If this option is set it will not automatically apply rules to all windows when the IPC socket is broken (happens on a crash or on restart). This option has no effect if --no-restart is used.

--no-restart

When the IPC socket is broken, i3king will automatically restart if this option is not set.

USAGE

i3king will match all new windows against the rules defined in I3_KING_RULE_FILE (~/.config/i3king/rules). If a rule matches the created window, the command associated with the rule will get passed to i3-msg.

The criterias a window can get matched against are

  • class
  • instance
  • title
  • window_type
  • window_role

Use GLOBAL rules to match any windows. global rules can have a blacklist for windows that will not trigger the rule.

A variant of the GLOBAL rule is DEFAULT rules, which works exactly like GLOBAL rules, except they only get triggered if the window didn't match any "normal" rules (regular GLOBAL rules are normal).

ON_CLOSE work like normal rules but will only trigger when a window is closed.

Just like in the i3 config the set directive is available, so you can make variables.

Some built in magic variables are avaible in the config:

  • $INSTANCE
  • $CLASS
  • $CONID
  • $WINID
  • $TITLE

TITLE is a rule type that works slightly different than the others. If triggered it will always execute the command title_format NEW_TITLE. And triggers on new windows and when a window title changes.

Instead of a command you specify: [option]/REGEX/ template Use $1,$2,$3... in the template to expand them to the corresponding capture group from the regex.

[option] is optional and can be either:

  • ~0 remove expanded $HOME/ from NEW_TITLE if this results in empty NEW_TITLE, a single ~ will be used
  • ~1 replace expanded $HOME with ~

EXAMPLE

# assuming the window class is "Thunar" and the window
# title is something like "/home/anon/.config/i3 - Thunar"

TITLE class=Thunar
  /^(.+)\s-\s(Thunar)$/ Filemanager: $2 - $1

# the above will result in NEW_TITLE: 
# Filemanager: Thunar - /home/anon/.config/i3

TITLE class=Thunar
  ~0/^(.+)\s-\s(Thunar)$/ $1

# the above will result in NEW_TITLE: 
# .config/i3

TITLE class=Thunar
  ~1/^(.+)\s-\s(Thunar)$/ $1

# the above will result in NEW_TITLE: 
# ~/.config/i3

EXAMPLE

GLOBAL \
  class=URxvt instance=htop, \
  instance=firefox
    title_format $INSTANCE

The above rule will set the title_format to the instance name of all windows, except a URxvt window with the instance name htop, and firefox windows.

If $I3_KING_RULES_FILE doesn't exist, a example rule file will get created. See that file for details about the syntax.

If you used to have for_window rules that triggered i3fyra --move commands. It is recommended to use the built in varialbe $CONID when executing i3fyra:

EXAMPLE

# old i3 version:
for_window [instance=qutebrowser] exec --no-startup-id i3fyra --move C

# with i3 king:
instance=qutebrowser
  exec --no-startup-id i3fyra --conid $CONID --move C

(the --conid option in i3fyra is brand new)

If the restart command is issued from i3, all windows lose gets new container IDs, marks are lost and other more or less strange things might happen to the layout. Another thing is that all open IPC sockets are closed and this means that any ipc subscriber would have to be restarted. i3king will, when the socket is broken, match all known windows against the rules again, and automatically restart itself. If you for some reason don't want this behaviour, try --no- restart and/or --no-apply options.

protip

Sending USR1 to the i3king process will restart i3king. Hint: kill -USR1 $(< "$XDG_RUNTIME_DIR/i3ass/i3king.pid")

ENVIRONMENT

BASHBUD_DIR

bashbud config dir location.

I3_KING_RULE_FILE

Path to file containing rules to be parsed.

I3_KING_PID_FILE

When i3king is running this file contains the pid of the i3king process. It is used by i3fyra to know if i3king is running, if it is, it will try to match windows against the rules when --float option toggles the floating state to tiled.

CONTACT

Send bugs and feature requests to:
https://github.com/budlabs/i3ass/issues

COPYRIGHT

Copyright (c) 2021-2023, budRich of budlabs
SPDX-License-Identifier: MIT

Clone this wiki locally