Skip to main content

kiln-client

kiln-client sends commands to kiln's IPC socket: a fixed verb surface plus a reflection layer over the object classes, so shell scripts can drive kiln without writing Lua. It is built as build/kiln-client; installation includes bash, zsh and fish completions. Select the instance with -s PATH or KILN_SOCK. Commands travel wrapped in kiln_ipc(...) so a verb and a Lua chunk stay distinct on the wire; scripts/kiln-eval in the source tree sends raw Lua to the same socket and is not installed.

kiln-client tag view web
kiln-client client list
kiln-client --json screen list
# {"result":[{"focus":"*","height":720,"name":"HEADLESS-1","scale":1,...}],"status":"ok"}

Invocation​

kiln-client [OPTIONS] COMMAND [ARGS...]
OptionMeaning
--jsonMachine-readable output: {"status":"ok","result":...} on success, {"status":"error","error":"..."} on failure.
-s, --socket PATHSocket path. Default: $KILN_SOCK, else $XDG_RUNTIME_DIR/kiln.sock.
-h, --helpUsage.

Any other --long word is treated as the verb's own flag (notify --urgency critical ...) and stops option parsing. Errors print ERROR ... and exit nonzero.

help and commands list what the running compositor supports:

kiln-client commands        # every verb, one per line
kiln-client help # every verb with its arguments
kiln-client help tag view # one verb, or one namespace: help tag
kiln-client reflect client # every method, getter, and setter of a class

Verbs​

74 verbs in the current build. Arguments in <angles> are required, [brackets] optional; a [client], [tag], or [screen] argument is a selector and defaults to the focused one.

Session​

VerbDoes
pingAnswer, so a caller can tell a live socket from a dead one
commands, help [verb...]Self-documentation
complete <index> [word...]Completion candidates (what the shell completions call)
eval <lua...>Run Lua in the compositor, the one door to everything the fixed verbs refuse
exec <command...>Spawn a command
notify [message...]Post a notification; --title/--timeout/--urgency anywhere in it
dirtyMark every screen for a re-declare
screenshot <path> [screen]Write a screen's pixels to a file
inspector [screen]Toggle the Clay debug inspector
idle <ms|off>Set or clear the idle timeout
lock, unlockSession lock
reloadRe-run the config, keeping the session up if it raises
quitEnd the session
input [setting] [value]List every input setting, or read or write one
theme get [key], theme set <key> <value>Theme readback and live writes
key listEvery key the config bound, as written
rule listEvery client rule the config declared, in order

client​

VerbDoes
client list / client visibleEvery client / only those on a selected tag, unminimized
client info [client]All properties of a client
client focus [client]Focus; also next or prev around the list
client close [client] / client kill [client]Polite close / SIGKILL
client raise / client lower [client]Restack within the band
client swap <client> <other>Swap layout positions
client movetotag <tag> [client] [screen]Replace a client's tags with one
client toggletag <tag> [client] [screen]Add or remove one tag, keeping the rest
client movetoscreen [screen] [client]Move to another screen's selected tag
client geometry [client]The solved box
client floating / fullscreen / maximized / minimized / sticky / urgent [client] [on|off|toggle]Read or write each state flag

tag​

VerbDoes
tag list [screen] / tag current [screen]Every tag / the selected ones
tag view <tag> [screen] / tag toggle <tag> [screen]Exclusive / additive selection
tag add <name> [screen] / tag delete <tag> [screen] / tag rename <tag> <new> [screen]Lifecycle
tag screen <tag> [screen]Which screen a tag lives on
tag gap / mwfact / master_count / column_count / carousel_width <tag> [value] [screen]Layout parameters, read or written

layout​

VerbDoes
layout listEvery layout name, families flattened into their variants
layout get [tag] [screen]The layout a tag is using
layout set <name> [tag] [screen]Set by name (tile.left, max, ...)
layout next / layout prev [tag] [screen]Step around the ring

screen and output​

VerbDoes
screen list / screen count / screen focusedEnumeration and focus state
screen focus [screen]Focus; also next or prev
screen clients [screen]Every client homed to a screen
screen scale [screen] [factor]Scale, read or written
screen workarea [screen]The box left after bars and layer reservations
output listEvery output as the hardware reports it
output mode <output> <w> <h> [hz] ([hz] is actually mHz: 60000 = 60 Hz; output list shows Hz) / position <output> <x> <y> / scale <output> <factor> / enabled <output> <on|off> / adaptive_sync <output> <on|off>Output configuration

Reflection​

The four reflection verbs reach anything the fixed verbs do not name, across the five classes (client, screen, tag, layer, notification):

kiln-client get client app_id:firefox title
kiln-client set tag focused gap 0
kiln-client call client focused raise
kiln-client reflect tag
VerbDoes
get <class> <selector> <property>Read a property off every object the selector resolves to
set <class> <selector> <property> <value>Write a property on every one
call <class> <selector> <method> [arg...]Invoke a method on every one
reflect [class]All methods, getters, setters, and properties of a class

Selectors​

Wherever a verb takes an object, the selector is one of:

FormResolves to
(omitted)The focused one, for verbs with an optional selector
allEvery object of the class
focusedThe focused client / screen / selected tag
previous (or mru)Clients only: the previously focused client
selectedTags only: every selected tag
a numberThe object with that handle
a nameThe object whose name matches exactly (tags, screens)
<field>:<pattern>Every object whose field matches the Lua pattern, e.g. app_id:firefox, title:%d+. A field holding an object compares by its name, so tag:web reads the way it looks.

Argument values get the same treatment in reverse: true/false and numbers convert, a quoted word stays a string (the only way to set a title of "42"), and a leading @ resolves an object inline, which is how a method taking one stays reachable:

kiln-client call client focused swap @client:app_id:foot

Shell completions​

Bash, zsh, and fish completions ship with the install (kiln-client.bash, _kiln-client, kiln-client.fish). All three query the running compositor through the complete verb, so they complete live verb names, tag names, and property names and never go stale against your build.

See also​