Add spawn-sh, spawn-at-startup-sh

Our top 10 most confusing config moments

2 files changed, 50 insertions, 1 deletions

diff --git a/docs/wiki/Configuration:-Key-Bindings.md b/docs/wiki/Configuration:-Key-Bindings.md
index 3295b0d7..7fbacd80 100644
--- a/docs/wiki/Configuration:-Key-Bindings.md
+++ b/docs/wiki/Configuration:-Key-Bindings.md
@@ -206,7 +206,8 @@ binds {
 > }
 > ```
 
-Currently, niri *does not* use a shell to run commands, which means that you need to manually separate arguments.
+For `spawn`, niri *does not* use a shell to run commands, which means that you need to manually separate arguments.
+See [`spawn-sh`](#spawn-sh) below for an action that uses a shell.
 
 ```kdl
 binds {
@@ -249,6 +250,37 @@ binds {
 }
 ```
 
+#### `spawn-sh`
+
+<sup>Since: next release</sup>
+
+Run a command through the shell.
+
+The argument is a single string that is passed verbatim to `sh`.
+You can use shell variables, pipelines, `~` expansion, and everything else as expected.
+
+```kdl
+binds {
+    // Works with spawn-sh: all arguments in the same string.
+    Mod+D { spawn-sh "alacritty -e /usr/bin/fish"; }
+
+    // Works with spawn-sh: shell variable ($MAIN_OUTPUT), ~ expansion.
+    Mod+T { spawn-sh "grim -o $MAIN_OUTPUT ~/screenshot.png"; }
+
+    // Works with spawn-sh: process substitution.
+    Mod+Q { spawn-sh "notify-send clipboard \"$(wl-paste)\""; }
+
+    // Works with spawn-sh: multiple commands.
+    Super+Alt+S { spawn-sh "pkill orca || exec orca"; }
+}
+```
+
+`spawn-sh "some command"` is equivalent to `spawn "sh" "-c" "some command"`—it's just a less confusing shorthand.
+Keep in mind that going through the shell incurs a tiny performance penalty compared to directly `spawn`ing some binary.
+
+Using `sh` is hardcoded, consistent with other compositors.
+If you want a different shell, write it out using `spawn`, e.g. `spawn "fish" "-c" "some fish command"`.
+
 #### `quit`
 
 Exit niri after showing a confirmation dialog to avoid accidentally triggering it.
diff --git a/docs/wiki/Configuration:-Miscellaneous.md b/docs/wiki/Configuration:-Miscellaneous.md
index f2d1010a..5231a79d 100644
--- a/docs/wiki/Configuration:-Miscellaneous.md
+++ b/docs/wiki/Configuration:-Miscellaneous.md
@@ -5,6 +5,7 @@ Here are all of these options at a glance:
 ```kdl
 spawn-at-startup "waybar"
 spawn-at-startup "alacritty"
+spawn-at-startup-sh "qs -c ~/source/qs/MyAwesomeShell"
 
 prefer-no-csd
 
@@ -71,6 +72,22 @@ spawn-at-startup "alacritty"
 Note that running niri as a systemd session supports xdg-desktop-autostart out of the box, which may be more convenient to use.
 Thanks to this, apps that you configured to autostart in GNOME will also "just work" in niri, without any manual `spawn-at-startup` configuration.
 
+### `spawn-at-startup-sh`
+
+<sup>Since: next release</sup>
+
+Add lines like this to run shell commands at niri startup.
+
+The argument is a single string that is passed verbatim to `sh`.
+You can use shell variables, pipelines, `~` expansion and everything else as expected.
+
+See detailed description in the docs for the [`spawn-sh` key binding action](./Configuration:-Key-Bindings.md#spawn-sh).
+
+```kdl
+// Pass all arguments in the same string.
+spawn-at-startup-sh "qs -c ~/source/qs/MyAwesomeShell"
+```
+
 ### `prefer-no-csd`
 
 This flag will make niri ask the applications to omit their client-side decorations.