Keys and actions commands

Keys belong to the terminal you run these from — they read that terminal's keybinding.kdl.

List shortcuts

koshi keys list
koshi keys list --mode normal
koshi keys list --scope default
koshi keys list --scope user

--mode takes one built-in mode: normal, locked, pane-placement, pane-move-choice, floating-pane-move, floating-pane-tray, or notification-center. --scope user lists the shortcuts in your keybinding.kdl. --scope default lists the built-in shortcuts, including each one your file rebinds or removes, with the source defaults (unbound).

Describe one sequence

koshi keys describe "<C-p> l"

Explains the binding on that sequence and every longer binding that starts with it: koshi keys describe "<C-t>" explains <C-t> n and <C-t> x. Each row shows the mode, the action with its display name and description, its scope, the layer it comes from, and whether it repeats from an open prefix (continuous). A built-in shortcut your file rebinds or removes shows with the source defaults (unbound) and a displaced_by field. A sequence that binds nothing and starts nothing exits 2.

Find conflicts

koshi keys conflicts

Checks the keybinding.kdl in the config directory the way a client checks it when it attaches: duplicate sequences, shorter prefixes that make longer bindings unreachable, reserved unlock problems, and warnings. It prints the whole answer, then exits 0 when a client would apply the file (verdict: apply) and 2 when a client would refuse it (verdict: reject). With no keybinding.kdl, it prints verdict: apply.

Validate a file

koshi keys validate path/to/keybinding.kdl

Checks the file at that path the same way, without adopting it, with the same exit codes.

List actions

koshi actions list
koshi actions list --format json

Lists every action with its internal command, scope, and cli_invocation: the shell command that runs it. An action that needs arguments names its own verb, such as koshi focus-tab; every other action names koshi actions run.

Explain one action

koshi actions explain core:new-pane
koshi actions explain core:new-pane --format json

Shows the action's name, description, scope, accepted targets, internal command, and examples. It takes a bare name (new-pane) or a full reference (core:new-pane). A binding in keybinding.kdl needs the full reference.

Run one action

koshi actions run next-tab
koshi actions run toggle-notification-center --client <CLIENT_ID>

Runs one action in a running session, as a key bound to it runs it. It takes a bare name or a full reference. --client names the client it runs for, defaulting to the issuing client, else the session's only attached one.

• An action that sends the session a command sends the same command: koshi actions run next-tab does what koshi next-tab does.
• An action that changes one client's screen, such as core:toggle-notification-center, runs in that client. If the client does not answer within 5 seconds, the command exits 1.
• An action that belongs to one input mode is refused in every other mode and exits 1.
• An action that needs arguments exits 2 and names its verb: core:focus-tab takes arguments; run koshi focus-tab.
• A name that is not an action exits 2 with unknown action: <name>.