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 and 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 and output.

window swap id [id]

Swap two windows with each other in the current context. If only one window id is given, the window is swapped with the currently focused window. This swap works across outputs.

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 send output_name|output_id

Send the focused window to a specific output.

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.

window merge left|right

Move the focused window into the neighboring column on the given side. This is only relevant for layouts that make use of columns. See argen(1) CONCEPTS for more information.

window split left|right

Pull the focused window out of the current column to the given side. This is only relevant for layouts that make use of columns. See argen(1) CONCEPTS for more information.

window resize width|height int

Resize the focused window along the given dimension. int follows the VALUE SYNTAX described above.

If the window is tiled, the layout decides how the window is resized within the layout.

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.

Outputs are addressed by name (e.g. DP-1) or by id. The id is a 16-digit hex string derived from the name and the output's make, model and serial.

The output order is defined from left to right in the global coordinate space, top to bottom among outputs sharing the same x coordinate.

output focus next|prev

Move focus to the next or previous output.

output focus name|id

Move focus to a specific 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.

scrolling

inner-padding int
Gap between windows.

outer-padding int

Gap between window and screen edges.

offset int

Horizontal scroll position starting at the first column.

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-captured 0xRRGGBB|0xRRGGBBAA

Set the border color of windows with an active screen capture session. This has a lower priority than focused.

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

Set the border color of unfocused windows.

config set capture-indicator bar|none

A reminder that a screen capture session is active (any window or output). bar (default) overlays layer-shell areas (bars/panels such as waybar) with a colored rectangle. none disables this feature.

config set capture-indicator-color 0xRRGGBB|0xRRGGBBAA

Color of the capture indicator overlay. Default is a semi-transparent red.

config set repeat rate delay

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

config set label-mode mode

Layouts can set labels for certain windows. 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, or argen(1) LAYOUTS for more information.

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_cmd

Run shell_cmd with `/bin/sh -c`. Note that shell_cmd 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 following interactive actions.

move-window

Move the window under the cursor. Forces the window to float.

resize-window

Resize the window under the cursor. If the window is tiled, the layout decides how the window is resized within the layout.

scroll

Pan the active layout of the output under the cursor. Only has an effect for the scrolling layout.

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.

In JSON mode each context contains its outputs, and each output the windows placed on it in layout order, with their position and size. See argen(1) CONCEPTS for the underlying model.

window list [--json]

List all windows.

In JSON mode each window is listed once, with its app id, title and the contexts it is attached to.

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)

39a69a1 2026-09-17 ARGENCTL(1)