ARGENCTL(1) General Commands Manual ARGENCTL(1)

argenctl - command-line interface for controlling argen

argenctl command [subcommand] [command specific arguments...]

argenctl is a command-line utility used to control and configure argen(1), a river(1)-based Wayland tiling window manager. It sends commands to argen over a Unix domain socket and prints responses to stdout/stderr.

  • n : set to absolute value
  • +n : increment by n
  • -n : decrement by n

The window id is a unique window identifier following the ext-foreign-toplevel-list-v1 protocol.

window focus next|prev

Focus the next or previous window in the current context/output.

window focus id

Focus a window by id. If the target window is not attached to the current context, this is a no-op.

window swap next|prev

Swap the focused window with the next or previous window in the current context/output.

window send next|prev

Send the focused window to the next or previous output in the current context. See also the OUTPUT ACTIONS section.

window attach id

Attach the window with id to the current context/output and focus it.

window detach [id]

Detach the window with id from the current context. If id is omitted, it detaches the focused window.

window toggle id

Toggle the attachment of id in the current context: detach if attached, attach and focus if detached.

window close [id]

Close the window with id. If id is omitted, closes the focused window.

window float

Toggle floating state for the focused window.

window fullscreen

Toggle fullscreen state for the focused window.

context new [name]

Create a new context. If name is omitted, a default name is assigned.

context switch name

Switch to the context named name.

context switch --last

Switch to the previously active context.

context rename [old-name] new-name

Rename a context. If old-name is omitted, renames the current context.

context close [name]

Close the context named name. If name is omitted, closes the current context.

The output order is defined from left to right in the global coordinate space.

output focus next|prev

Move focus to the next or previous output.

layout switch next|prev

Switch to the next or previous layout in the current context and output.

layout switch layout

Switch the layout in the current context and output by name.

layout set [--name layout] key value

Adjust a layout parameter interactively in the current context and output. If you want to set global default values instead, see the CONFIG ACTIONS section.

--name selects which layout to configure. If omitted, the active layout is used.

float and int follow the value syntax described above.

Supported parameters by layout.

stacktile

primary-ratio float
Width ratio of the primary window. Default: 0.5.

secondary-ratio float

Height ratio of the secondary window in the right column. Default: 0.5.

inner-padding int

Gap between windows.

outer-padding int

Gap between windows and screen edges.

monocle

outer-padding int
Gap between window and screen edges.

columns

inner-padding int
Gap between windows.

outer-padding int

Gap between window and screen edges.

Global window manager configuration.

float and int follows the value syntax described above.

config set border-width int

Set the window border width in pixels.

config set border-color-focused 0xRRGGBB|0xRRGGBBAA

Set the border color of focused windows.

config set border-color-unfocused 0xRRGGBB|0xRRGGBBAA

Set the border color of unfocused windows.

config set repeat rate delay

Set key repeat rate (keys per second) and delay (milliseconds).

config set label-mode transient[:ms]|modifier[:key]|always|never

Certain layouts can indicate window labels to the user. Available modes:

transient[:ms]

Labels are shown for ms after a relevant state change. Default ms is 1500ms.

modifier[:key]

Labels are shown while the modifier key is pressed. Default key is super.

always

Labels are always shown.

never

Labels are never shown.

config set default-layout layout

Set the default layout for new contexts and outputs. For available layouts, see the LAYOUT ACTIONS section above.

config set layout key value

Set global default values for layout. These defaults are applied when a new context or output is created. For available layouts and parameters, see the LAYOUT ACTIONS section above.

There are two pre-existing modes: normal and locked. normal is the initial mode on startup. The locked mode is automatically entered while the session is locked (e.g. due to a screenlocker). It cannot be entered or exited manually.

mode declare name

Declare a new input mode named name.

mode enter name

Switch to the input mode named name.

exit [--argen-only]

Exit the river compositor and end the Wayland session. With --argen-only, only close argen without exiting river. This may leave river in an unusable state.

This can be used to run external commands or programs. Processes started with this are double-forked and therefore detached from argen or river.

exec cmd [arg...]

Run cmd with the given arguments.

sh shell_command

Run shell_command with `/bin/sh -c`. Note that shell_command has to be a single argument. This can be a command using shell pipes or even an inline script over multiple lines.

Argenctl itself can be called within such an inline script to allow complex interactions with argen. See the `example/init` file in the project repository for example uses.

binding set [--repeat] mode modifiers keysym action

Create a key binding.

--repeat: If passed, activate binding repeatedly until key release.

mode: Name of the mode for which to create the binding. The binding is only activated if mode is active. See also the MODE ACTIONS section.

modifiers: +-separated list of modifier names. The following are availabe:

  • Super
  • Shift
  • Control
  • Alt
  • Mod3
  • Mod5
  • None

Alt and Super are also known as Mod1 and Mod4 respectively. None allows creating bindings without modifiers.

keysym: An XKB key symbol name. They are matched case-insensitive.

For the complete list see /usr/include/xkbcommon/xkbcommon-keysyms.h.

action: Any argenctl action (see above).

Overrides an existing binding for this mode modifiers keysym combination.

binding unset mode modifiers keysym

Remove the binding.

pointer-binding set mode modifiers button action

Create a pointer binding.

mode: Name of the mode for which to create the binding. The binding is only activated if mode is active. See also the MODE ACTIONS section.

modifiers: Follows the same syntax as for binding set.

button: A Linux input event code name, commonly used are the mouse the buttons BTN_LEFT, BTN_RIGHT, and BTN_MIDDLE.

A complete list may be found in /usr/include/linux/input-event-codes.h.

action: Any argenctl action, or one of the interactive actions move-window or resize-window.

Overrides an existing bindind for this mode modifiers button combination.

pointer-binding unset mode modifiers button

Remove the pointer binding.

rule add type [--app-id glob] [--title glob]

Rules match the app-id and title of windows against a glob pattern. A glob is a string that may optionally have an * at the beginning and/or end. A * in a glob matches zero or more arbitrary characters in the app-id or title. Omitting --app-id or --title matches any app-id or title. A glob containing * should be quoted to prevent the shell from expanding it.

If multiple rules from the same category (e.g. float and no-float) match, the most recently added one takes effect. Rules from different categories don't interact.

The following rule type are available:

float | no-float

Float windows or force them to be tiled, overriding floating heuristics.

This rule is applied when a window spawns or when its app-id or title changes.

tearing | no-tearing

Overrides the window's presentation hint for vsync (no-tearing) or async (tearing). Note that while the policy is window-based, the actual page flipping mode is set per output. In the case of argen, the mode is determined by the top-most fullscreen window on the output, or the most recently focused window if none is fullscreen.

rule del type [--app-id glob] [--title glob]

Delete the rule created using rule add with the given arguments. Note that e.g. float and no-float are equivalent here and will delete a float or no-float rule regardless.

The default output format is one item per line, with tab-separated fields where applicable, and can be used together with tools like dmenu(1), rofi(1), or fuzzel(1).

The --json flag outputs information in a JSON structure. This provides additional information compared to the default output and allows filtering with tools like jq(1).

context list [--json]

List all contexts. Sorted by most-recently used order.

window list [--json]

List all windows.

output list [--json]

List all outputs.

rule list [--json]

List all window rules. The * glob pattern is shown as null in JSON mode.

mode get

Print the name of the current input mode.

layout get

Print the name of the current layout.

argen(1), river(1), dmenu(1), rofi(1), fuzzel(1), jq(1)

v0.1.2 2026-07-19 ARGENCTL(1)