Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs(shell): make config shell help the setup home (#4344)

Maximilian Roosc98f5f502836
diff --git a/docs/src/content/docs/config.md b/docs/src/content/docs/config.md
index 61b300c8e..11bcb83b7 100644
--- a/docs/src/content/docs/config.md
+++ b/docs/src/content/docs/config.md
@@ -617,15 +617,7 @@ Aliases defined here are shared with teammates. For personal aliases, use the [u
# Shell Integration
-Worktrunk needs shell integration to change directories when switching worktrees. Install with:
-
-```console
-$ wt config shell install
-```
-
-For manual setup, see `wt config shell init --help`.
-
-Without shell integration, `wt switch` prints the target directory but cannot `cd` into it.
+See [`wt config shell`](#wt-config-shell) for setup, activation, and current-shell diagnostics.
### First-run prompts
@@ -743,6 +735,213 @@ Global Options:
# Subcommands
+## wt config shell
+
+Shell integration setup.
+
+A subprocess cannot change its parent shell's directory. Shell integration defines a function that runs the Worktrunk binary, then changes the shell's directory when the command requests it. It also enables tab completion.
+
+### Setup
+
+```console
+$ wt config shell install
+```
+
+Start a new shell after installation to load the wrapper. Invoke `wt` by name. Running a binary path or `git wt` bypasses the wrapper, so the shell's directory stays unchanged.
+
+- `wt config shell install --help` — installation options
+- `wt config shell init --help` — manual setup
+- `wt config shell uninstall` — remove the integration
+
+### Check the current shell
+
+```console
+$ wt config show
+```
+
+The SHELL INTEGRATION section reports whether the wrapper is active in the current session. Installation and activation are separate: a configured shell can still be running without the wrapper until its config is reloaded.
+
+In bash, zsh, or fish, `type wt` checks that `wt` resolves to a function. In PowerShell, `Get-Command wt -All` lists the Function and Application definitions.
+
+See [worktrunk.dev/shell-integration](/shell-integration/) for warning messages, installed files, and wrapper behavior.
+
+### Command reference
+
+```text wt-command-reference
+wt config shell - Shell integration setup
+
+Usage: wt config shell [OPTIONS] <COMMAND>
+
+Commands:
+ init Generate shell integration code
+ install Write shell integration to config files
+ uninstall Remove shell integration from config files
+ show-theme Show output theme samples
+
+Options:
+ -h, --help
+ Print help (see a summary with '-h')
+```
+
+## wt config shell init
+
+Generate shell integration code.
+
+Outputs shell code for `eval` or sourcing. Most users should run `wt config shell install` instead, which adds this automatically.
+
+### Manual setup
+
+For bash, fish, zsh, and PowerShell, add the matching line to the shell config. For Nushell, run the command to save the wrapper in its autoload directory.
+
+Bash (~/.bashrc):
+```console
+$ eval "$(wt config shell init bash)"
+```
+
+Fish (~/.config/fish/config.fish):
+```fish
+wt config shell init fish | source
+```
+
+Zsh (~/.zshrc):
+```zsh
+eval "$(wt config shell init zsh)"
+```
+
+Nushell 0.113+ <span class="badge-experimental"></span> — save to vendor autoload directory:
+```console
+$ wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join wt.nu)
+```
+
+PowerShell ($PROFILE):
+```powershell
+Invoke-Expression (& wt config shell init powershell | Out-String)
+```
+
+### Command reference
+
+```text wt-command-reference
+wt config shell init - Generate shell integration code
+
+Usage: wt config shell init [OPTIONS] <bash|fish|nu|zsh|powershell>
+
+Arguments:
+ <bash|fish|nu|zsh|powershell>
+ Shell to generate code for
+
+ [possible values: bash, fish, nu, zsh, powershell]
+
+Options:
+ --cmd <CMD>
+ Command name for shell integration (defaults to binary name)
+
+ Use this to create shell integration for an alternate command name. For example,
+ --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt
+ conflicts with Windows Terminal.
+
+ -h, --help
+ Print help (see a summary with '-h')
+```
+
+## wt config shell install
+
+Write shell integration to config files.
+
+Appends an initialization line to bash, zsh, and PowerShell config files. For fish and Nushell, it replaces the autoloaded wrapper file; fish also gets a separate completion file. See [worktrunk.dev/shell-integration](/shell-integration/#files-created) for their locations.
+
+### Examples
+
+Install for all detected shells:
+```console
+$ wt config shell install
+```
+
+Install for specific shell only:
+```console
+$ wt config shell install zsh
+```
+
+Shows proposed changes and waits for confirmation before modifying any files.
+Use --yes to skip confirmation.
+
+### Command reference
+
+```text wt-command-reference
+wt config shell install - Write shell integration to config files
+
+Usage: wt config shell install [OPTIONS] [bash|fish|nu|zsh|powershell]
+
+Arguments:
+ [bash|fish|nu|zsh|powershell]
+ Shell to install (default: all)
+
+ [possible values: bash, fish, nu, zsh, powershell]
+
+Options:
+ --dry-run
+ Show what would be changed
+
+ --cmd <CMD>
+ Command name for shell integration (defaults to binary name)
+
+ Use this to create shell integration for an alternate command name. For example,
+ --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt
+ conflicts with Windows Terminal.
+
+ -h, --help
+ Print help (see a summary with '-h')
+```
+
+## wt config shell uninstall
+
+Remove shell integration from config files.
+
+Removes Worktrunk initialization lines from bash, zsh, and PowerShell config files, and Worktrunk wrapper and completion files for fish and Nushell.
+
+### Examples
+
+Uninstall from all shells:
+```console
+$ wt config shell uninstall
+```
+
+Uninstall from specific shell only:
+```console
+$ wt config shell uninstall zsh
+```
+
+Skip confirmation prompt:
+```console
+$ wt config shell uninstall --yes
+```
+
+### Version tolerance
+
+Uninstall removes every worktrunk-managed integration it finds, regardless of:
+- Binary name it was installed under (`wt`, `git-wt`, …)
+- Minor syntax variations between versions
+
+### Command reference
+
+```text wt-command-reference
+wt config shell uninstall - Remove shell integration from config files
+
+Usage: wt config shell uninstall [OPTIONS] [bash|fish|nu|zsh|powershell]
+
+Arguments:
+ [bash|fish|nu|zsh|powershell]
+ Shell to uninstall (default: all)
+
+ [possible values: bash, fish, nu, zsh, powershell]
+
+Options:
+ --dry-run
+ Show what would be changed
+
+ -h, --help
+ Print help (see a summary with '-h')
+```
+
## wt config show
Show configuration files & locations.
diff --git a/docs/src/content/docs/shell-integration.md b/docs/src/content/docs/shell-integration.md
index cd65caf8f..4122952cf 100644
--- a/docs/src/content/docs/shell-integration.md
+++ b/docs/src/content/docs/shell-integration.md
@@ -4,63 +4,35 @@ description: "How Worktrunk's shell wrapper changes the parent shell's directory
sidebar:
order: 25
---
-Shell integration is what lets `wt switch` change your shell's directory. This page covers how it works, what it installs, and how to fix it when it doesn't.
+[`wt config shell`](/config/#wt-config-shell) covers setup, activation, and current-shell diagnostics. This guide covers installed files, warning messages, and wrapper behavior.
## Why shell integration exists
-A subprocess cannot change its parent shell's directory. When `wt switch feature` runs, the `wt` binary is a child process and cannot `cd` the terminal.
-
-Worktrunk solves this with a file directive: the shell wrapper creates one temp file, `wt` writes the target directory to it, and the wrapper changes directory after `wt` exits. `--execute` runs directly inside `wt`. See [How the shell wrapper works](#how-the-shell-wrapper-works) for the steps and a simplified implementation.
+The [shell integration overview](/config/#wt-config-shell) explains why directory switching needs a shell function. [How the shell wrapper works](#how-the-shell-wrapper-works) describes the directive mechanism.
## Installation
-```bash
-# Auto-install for all shells (bash, zsh, fish, nushell (experimental), PowerShell)
-wt config shell install
-
-# Or manual installation - add to the shell config:
-# bash (~/.bashrc):
-eval "$(wt config shell init bash)"
-
-# zsh (~/.zshrc):
-eval "$(wt config shell init zsh)"
-
-# fish (~/.config/fish/config.fish):
-wt config shell init fish | source
-
-# nushell 0.113+ (experimental) — save to vendor autoload directory:
-wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join wt.nu)
-
-# PowerShell ($PROFILE):
-Invoke-Expression (& wt config shell init powershell | Out-String)
-```
+See [`wt config shell install`](/config/#wt-config-shell-install) for automatic installation and [`wt config shell init`](/config/#wt-config-shell-init) for manual setup in each supported shell.
## Files created
-`wt config shell install` writes:
+[`wt config shell install`](/config/#wt-config-shell-install) uses these locations:
-- **Bash**: adds a line to `~/.bashrc`
-- **Zsh**: adds a line to `~/.zshrc` (or `$ZDOTDIR/.zshrc`)
-- **Fish**: creates `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish` (under `$XDG_CONFIG_HOME/fish` when that is set)
-- **Nushell 0.113+** <span class="badge-experimental"></span>: creates `wt.nu` in Nushell's user vendor-autoload directory — the last entry of `$nu.vendor-autoload-dirs`, under `$nu.data-dir` (typically `~/.local/share/nushell/vendor/autoload` on Linux, `~/Library/Application Support/nushell/vendor/autoload` on macOS)
-- **PowerShell** (Windows): creates both profile files if they don't exist:
+- **Bash**: `~/.bashrc`
+- **Zsh**: `~/.zshrc` (or `$ZDOTDIR/.zshrc`)
+- **Fish**: `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish` (under `$XDG_CONFIG_HOME/fish` when that is set)
+- **Nushell 0.113+** <span class="badge-experimental"></span>: `wt.nu` in Nushell's user vendor-autoload directory — the last entry of `$nu.vendor-autoload-dirs`, under `$nu.data-dir` (typically `~/.local/share/nushell/vendor/autoload` on Linux, `~/Library/Application Support/nushell/vendor/autoload` on macOS)
+- **PowerShell** (Windows): both profile files:
- `Documents/PowerShell/Microsoft.PowerShell_profile.ps1` (PowerShell 7+)
- `Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1` (Windows PowerShell 5.1)
-Fish and Nushell wrappers live at a path named after the command, so install writes that file whole, replacing an existing `functions/wt.fish`, `completions/wt.fish`, or `wt.nu`. Bash, zsh, and PowerShell rc files hold the rest of a shell's setup, so install only appends a line to those.
-
**PowerShell detection on Windows:** When running from cmd.exe or PowerShell, both PowerShell profile files are created automatically. When running from Git Bash or MSYS2, PowerShell is skipped (use `wt config shell install powershell` to create the profiles explicitly).
-**To remove:** `wt config shell uninstall`.
+See [`wt config shell uninstall`](/config/#wt-config-shell-uninstall) for removal.
## Checking status
-```bash
-# Show shell integration status
-wt config show
-```
-
-The RUNTIME section shows whether shell integration is active for the current session.
+The [current-shell checks](/config/#wt-config-shell) explain how to inspect installation and activation with `wt config show` and the shell's command lookup.
## Warning messages
@@ -74,9 +46,9 @@ When shell integration isn't working, `wt switch` shows a warning explaining why
### "shell integration not installed"
-**Meaning**: The current shell's config file doesn't have the `eval "$(wt config shell init ...)"` line. The current shell is detected from the process tree (falling back to `$SHELL`), so this refers to the shell `wt` was actually invoked from, not necessarily the login shell.
+**Meaning**: The current shell has no installed Worktrunk initialization line or wrapper file. The current shell is detected from the process tree (falling back to `$SHELL`), so this refers to the shell `wt` was actually invoked from, not necessarily the login shell.
-**Fix**: Run `wt config shell install` or add the line manually.
+**Fix**: Run `wt config shell install` or follow the [manual setup](/config/#wt-config-shell-init).
### "shell integration installed but not active"
@@ -193,11 +165,11 @@ grep -n "wt config shell init" ~/.bashrc
# zsh
grep -n "wt config shell init" ~/.zshrc
-# fish
+# fish (manual setup)
grep -n "wt config shell init" ~/.config/fish/config.fish
```
-This should show the `eval` line with its line number.
+These commands show the initialization line and its line number. `wt config shell install` writes fish and Nushell wrapper files instead; check those at the locations listed under [Files created](#files-created).
### 4. Check whether directive files are set
@@ -255,5 +227,5 @@ If you see path issues, make sure you're on a recent Git for Windows version.
## See also
-- [`wt config`](/config/#shell-integration) — shell integration commands
+- [`wt config shell`](/config/#wt-config-shell) — setup and current-shell diagnostics
- [FAQ: What files does Worktrunk create?](/faq/#what-files-does-worktrunk-create)
diff --git a/docs/tests/built-site.test.mjs b/docs/tests/built-site.test.mjs
index 572bbb8af..b843f10ff 100644
--- a/docs/tests/built-site.test.mjs
+++ b/docs/tests/built-site.test.mjs
@@ -225,7 +225,7 @@ test('build preserves the public route contract', async () => {
assert.ok(configToc, 'config page is missing its desktop table of contents');
assert.equal(
[...configToc.matchAll(/<a href="#[^"]+"/g)].length,
- 32,
+ 36,
'config table of contents should expose overview and structural section headings only',
);
for (const [id, title] of [
@@ -234,6 +234,10 @@ test('build preserves the public route contract', async () => {
['shell-integration', 'Shell Integration'],
['other', 'Other'],
['subcommands', 'Subcommands'],
+ ['wt-config-shell', 'wt config shell'],
+ ['wt-config-shell-init', 'wt config shell init'],
+ ['wt-config-shell-install', 'wt config shell install'],
+ ['wt-config-shell-uninstall', 'wt config shell uninstall'],
]) {
assert.match(
configToc,
diff --git a/plugins/worktrunk/skills/worktrunk/reference/config.md b/plugins/worktrunk/skills/worktrunk/reference/config.md
index 9ba21ecb6..a7aff2f5c 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/config.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/config.md
@@ -609,15 +609,7 @@ Aliases defined here are shared with teammates. For personal aliases, use the [u
# Shell Integration
-Worktrunk needs shell integration to change directories when switching worktrees. Install with:
-
-```console
-$ wt config shell install
-```
-
-For manual setup, see `wt config shell init --help`.
-
-Without shell integration, `wt switch` prints the target directory but cannot `cd` into it.
+See [`wt config shell`](#wt-config-shell) for setup, activation, and current-shell diagnostics.
### First-run prompts
@@ -735,6 +727,213 @@ Global Options:
# Subcommands
+## wt config shell
+
+Shell integration setup.
+
+A subprocess cannot change its parent shell's directory. Shell integration defines a function that runs the Worktrunk binary, then changes the shell's directory when the command requests it. It also enables tab completion.
+
+### Setup
+
+```console
+$ wt config shell install
+```
+
+Start a new shell after installation to load the wrapper. Invoke `wt` by name. Running a binary path or `git wt` bypasses the wrapper, so the shell's directory stays unchanged.
+
+- `wt config shell install --help` — installation options
+- `wt config shell init --help` — manual setup
+- `wt config shell uninstall` — remove the integration
+
+### Check the current shell
+
+```console
+$ wt config show
+```
+
+The SHELL INTEGRATION section reports whether the wrapper is active in the current session. Installation and activation are separate: a configured shell can still be running without the wrapper until its config is reloaded.
+
+In bash, zsh, or fish, `type wt` checks that `wt` resolves to a function. In PowerShell, `Get-Command wt -All` lists the Function and Application definitions.
+
+See [worktrunk.dev/shell-integration](https://worktrunk.dev/shell-integration/) for warning messages, installed files, and wrapper behavior.
+
+### Command reference
+
+```
+wt config shell - Shell integration setup
+
+Usage: wt config shell [OPTIONS] <COMMAND>
+
+Commands:
+ init Generate shell integration code
+ install Write shell integration to config files
+ uninstall Remove shell integration from config files
+ show-theme Show output theme samples
+
+Options:
+ -h, --help
+ Print help (see a summary with '-h')
+```
+
+## wt config shell init
+
+Generate shell integration code.
+
+Outputs shell code for `eval` or sourcing. Most users should run `wt config shell install` instead, which adds this automatically.
+
+### Manual setup
+
+For bash, fish, zsh, and PowerShell, add the matching line to the shell config. For Nushell, run the command to save the wrapper in its autoload directory.
+
+Bash (~/.bashrc):
+```console
+$ eval "$(wt config shell init bash)"
+```
+
+Fish (~/.config/fish/config.fish):
+```fish
+wt config shell init fish | source
+```
+
+Zsh (~/.zshrc):
+```zsh
+eval "$(wt config shell init zsh)"
+```
+
+Nushell 0.113+ [experimental] — save to vendor autoload directory:
+```console
+$ wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join wt.nu)
+```
+
+PowerShell ($PROFILE):
+```powershell
+Invoke-Expression (& wt config shell init powershell | Out-String)
+```
+
+### Command reference
+
+```
+wt config shell init - Generate shell integration code
+
+Usage: wt config shell init [OPTIONS] <bash|fish|nu|zsh|powershell>
+
+Arguments:
+ <bash|fish|nu|zsh|powershell>
+ Shell to generate code for
+
+ [possible values: bash, fish, nu, zsh, powershell]
+
+Options:
+ --cmd <CMD>
+ Command name for shell integration (defaults to binary name)
+
+ Use this to create shell integration for an alternate command name. For example,
+ --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt
+ conflicts with Windows Terminal.
+
+ -h, --help
+ Print help (see a summary with '-h')
+```
+
+## wt config shell install
+
+Write shell integration to config files.
+
+Appends an initialization line to bash, zsh, and PowerShell config files. For fish and Nushell, it replaces the autoloaded wrapper file; fish also gets a separate completion file. See [worktrunk.dev/shell-integration](https://worktrunk.dev/shell-integration/#files-created) for their locations.
+
+### Examples
+
+Install for all detected shells:
+```console
+$ wt config shell install
+```
+
+Install for specific shell only:
+```console
+$ wt config shell install zsh
+```
+
+Shows proposed changes and waits for confirmation before modifying any files.
+Use --yes to skip confirmation.
+
+### Command reference
+
+```
+wt config shell install - Write shell integration to config files
+
+Usage: wt config shell install [OPTIONS] [bash|fish|nu|zsh|powershell]
+
+Arguments:
+ [bash|fish|nu|zsh|powershell]
+ Shell to install (default: all)
+
+ [possible values: bash, fish, nu, zsh, powershell]
+
+Options:
+ --dry-run
+ Show what would be changed
+
+ --cmd <CMD>
+ Command name for shell integration (defaults to binary name)
+
+ Use this to create shell integration for an alternate command name. For example,
+ --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt
+ conflicts with Windows Terminal.
+
+ -h, --help
+ Print help (see a summary with '-h')
+```
+
+## wt config shell uninstall
+
+Remove shell integration from config files.
+
+Removes Worktrunk initialization lines from bash, zsh, and PowerShell config files, and Worktrunk wrapper and completion files for fish and Nushell.
+
+### Examples
+
+Uninstall from all shells:
+```console
+$ wt config shell uninstall
+```
+
+Uninstall from specific shell only:
+```console
+$ wt config shell uninstall zsh
+```
+
+Skip confirmation prompt:
+```console
+$ wt config shell uninstall --yes
+```
+
+### Version tolerance
+
+Uninstall removes every worktrunk-managed integration it finds, regardless of:
+- Binary name it was installed under (`wt`, `git-wt`, …)
+- Minor syntax variations between versions
+
+### Command reference
+
+```
+wt config shell uninstall - Remove shell integration from config files
+
+Usage: wt config shell uninstall [OPTIONS] [bash|fish|nu|zsh|powershell]
+
+Arguments:
+ [bash|fish|nu|zsh|powershell]
+ Shell to uninstall (default: all)
+
+ [possible values: bash, fish, nu, zsh, powershell]
+
+Options:
+ --dry-run
+ Show what would be changed
+
+ -h, --help
+ Print help (see a summary with '-h')
+```
+
## wt config show
Show configuration files & locations.
diff --git a/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md b/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md
index f259d49e8..5b0d33b33 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md
@@ -1,62 +1,34 @@
# Shell integration
-Shell integration is what lets `wt switch` change your shell's directory. This page covers how it works, what it installs, and how to fix it when it doesn't.
+[`wt config shell`](https://worktrunk.dev/config/#wt-config-shell) covers setup, activation, and current-shell diagnostics. This guide covers installed files, warning messages, and wrapper behavior.
## Why shell integration exists
-A subprocess cannot change its parent shell's directory. When `wt switch feature` runs, the `wt` binary is a child process and cannot `cd` the terminal.
-
-Worktrunk solves this with a file directive: the shell wrapper creates one temp file, `wt` writes the target directory to it, and the wrapper changes directory after `wt` exits. `--execute` runs directly inside `wt`. See [How the shell wrapper works](#how-the-shell-wrapper-works) for the steps and a simplified implementation.
+The [shell integration overview](https://worktrunk.dev/config/#wt-config-shell) explains why directory switching needs a shell function. [How the shell wrapper works](#how-the-shell-wrapper-works) describes the directive mechanism.
## Installation
-```bash
-# Auto-install for all shells (bash, zsh, fish, nushell (experimental), PowerShell)
-wt config shell install
-
-# Or manual installation - add to the shell config:
-# bash (~/.bashrc):
-eval "$(wt config shell init bash)"
-
-# zsh (~/.zshrc):
-eval "$(wt config shell init zsh)"
-
-# fish (~/.config/fish/config.fish):
-wt config shell init fish | source
-
-# nushell 0.113+ (experimental) — save to vendor autoload directory:
-wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join wt.nu)
-
-# PowerShell ($PROFILE):
-Invoke-Expression (& wt config shell init powershell | Out-String)
-```
+See [`wt config shell install`](https://worktrunk.dev/config/#wt-config-shell-install) for automatic installation and [`wt config shell init`](https://worktrunk.dev/config/#wt-config-shell-init) for manual setup in each supported shell.
## Files created
-`wt config shell install` writes:
+[`wt config shell install`](https://worktrunk.dev/config/#wt-config-shell-install) uses these locations:
-- **Bash**: adds a line to `~/.bashrc`
-- **Zsh**: adds a line to `~/.zshrc` (or `$ZDOTDIR/.zshrc`)
-- **Fish**: creates `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish` (under `$XDG_CONFIG_HOME/fish` when that is set)
-- **Nushell 0.113+** [experimental]: creates `wt.nu` in Nushell's user vendor-autoload directory — the last entry of `$nu.vendor-autoload-dirs`, under `$nu.data-dir` (typically `~/.local/share/nushell/vendor/autoload` on Linux, `~/Library/Application Support/nushell/vendor/autoload` on macOS)
-- **PowerShell** (Windows): creates both profile files if they don't exist:
+- **Bash**: `~/.bashrc`
+- **Zsh**: `~/.zshrc` (or `$ZDOTDIR/.zshrc`)
+- **Fish**: `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish` (under `$XDG_CONFIG_HOME/fish` when that is set)
+- **Nushell 0.113+** [experimental]: `wt.nu` in Nushell's user vendor-autoload directory — the last entry of `$nu.vendor-autoload-dirs`, under `$nu.data-dir` (typically `~/.local/share/nushell/vendor/autoload` on Linux, `~/Library/Application Support/nushell/vendor/autoload` on macOS)
+- **PowerShell** (Windows): both profile files:
- `Documents/PowerShell/Microsoft.PowerShell_profile.ps1` (PowerShell 7+)
- `Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1` (Windows PowerShell 5.1)
-Fish and Nushell wrappers live at a path named after the command, so install writes that file whole, replacing an existing `functions/wt.fish`, `completions/wt.fish`, or `wt.nu`. Bash, zsh, and PowerShell rc files hold the rest of a shell's setup, so install only appends a line to those.
-
**PowerShell detection on Windows:** When running from cmd.exe or PowerShell, both PowerShell profile files are created automatically. When running from Git Bash or MSYS2, PowerShell is skipped (use `wt config shell install powershell` to create the profiles explicitly).
-**To remove:** `wt config shell uninstall`.
+See [`wt config shell uninstall`](https://worktrunk.dev/config/#wt-config-shell-uninstall) for removal.
## Checking status
-```bash
-# Show shell integration status
-wt config show
-```
-
-The RUNTIME section shows whether shell integration is active for the current session.
+The [current-shell checks](https://worktrunk.dev/config/#wt-config-shell) explain how to inspect installation and activation with `wt config show` and the shell's command lookup.
## Warning messages
@@ -70,9 +42,9 @@ When shell integration isn't working, `wt switch` shows a warning explaining why
### "shell integration not installed"
-**Meaning**: The current shell's config file doesn't have the `eval "$(wt config shell init ...)"` line. The current shell is detected from the process tree (falling back to `$SHELL`), so this refers to the shell `wt` was actually invoked from, not necessarily the login shell.
+**Meaning**: The current shell has no installed Worktrunk initialization line or wrapper file. The current shell is detected from the process tree (falling back to `$SHELL`), so this refers to the shell `wt` was actually invoked from, not necessarily the login shell.
-**Fix**: Run `wt config shell install` or add the line manually.
+**Fix**: Run `wt config shell install` or follow the [manual setup](https://worktrunk.dev/config/#wt-config-shell-init).
### "shell integration installed but not active"
@@ -189,11 +161,11 @@ grep -n "wt config shell init" ~/.bashrc
# zsh
grep -n "wt config shell init" ~/.zshrc
-# fish
+# fish (manual setup)
grep -n "wt config shell init" ~/.config/fish/config.fish
```
-This should show the `eval` line with its line number.
+These commands show the initialization line and its line number. `wt config shell install` writes fish and Nushell wrapper files instead; check those at the locations listed under [Files created](#files-created).
### 4. Check whether directive files are set
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index 9ba21ecb6..a7aff2f5c 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -609,15 +609,7 @@ Aliases defined here are shared with teammates. For personal aliases, use the [u
# Shell Integration
-Worktrunk needs shell integration to change directories when switching worktrees. Install with:
-
-```console
-$ wt config shell install
-```
-
-For manual setup, see `wt config shell init --help`.
-
-Without shell integration, `wt switch` prints the target directory but cannot `cd` into it.
+See [`wt config shell`](#wt-config-shell) for setup, activation, and current-shell diagnostics.
### First-run prompts
@@ -735,6 +727,213 @@ Global Options:
# Subcommands
+## wt config shell
+
+Shell integration setup.
+
+A subprocess cannot change its parent shell's directory. Shell integration defines a function that runs the Worktrunk binary, then changes the shell's directory when the command requests it. It also enables tab completion.
+
+### Setup
+
+```console
+$ wt config shell install
+```
+
+Start a new shell after installation to load the wrapper. Invoke `wt` by name. Running a binary path or `git wt` bypasses the wrapper, so the shell's directory stays unchanged.
+
+- `wt config shell install --help` — installation options
+- `wt config shell init --help` — manual setup
+- `wt config shell uninstall` — remove the integration
+
+### Check the current shell
+
+```console
+$ wt config show
+```
+
+The SHELL INTEGRATION section reports whether the wrapper is active in the current session. Installation and activation are separate: a configured shell can still be running without the wrapper until its config is reloaded.
+
+In bash, zsh, or fish, `type wt` checks that `wt` resolves to a function. In PowerShell, `Get-Command wt -All` lists the Function and Application definitions.
+
+See [worktrunk.dev/shell-integration](https://worktrunk.dev/shell-integration/) for warning messages, installed files, and wrapper behavior.
+
+### Command reference
+
+```
+wt config shell - Shell integration setup
+
+Usage: wt config shell [OPTIONS] <COMMAND>
+
+Commands:
+ init Generate shell integration code
+ install Write shell integration to config files
+ uninstall Remove shell integration from config files
+ show-theme Show output theme samples
+
+Options:
+ -h, --help
+ Print help (see a summary with '-h')
+```
+
+## wt config shell init
+
+Generate shell integration code.
+
+Outputs shell code for `eval` or sourcing. Most users should run `wt config shell install` instead, which adds this automatically.
+
+### Manual setup
+
+For bash, fish, zsh, and PowerShell, add the matching line to the shell config. For Nushell, run the command to save the wrapper in its autoload directory.
+
+Bash (~/.bashrc):
+```console
+$ eval "$(wt config shell init bash)"
+```
+
+Fish (~/.config/fish/config.fish):
+```fish
+wt config shell init fish | source
+```
+
+Zsh (~/.zshrc):
+```zsh
+eval "$(wt config shell init zsh)"
+```
+
+Nushell 0.113+ [experimental] — save to vendor autoload directory:
+```console
+$ wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join wt.nu)
+```
+
+PowerShell ($PROFILE):
+```powershell
+Invoke-Expression (& wt config shell init powershell | Out-String)
+```
+
+### Command reference
+
+```
+wt config shell init - Generate shell integration code
+
+Usage: wt config shell init [OPTIONS] <bash|fish|nu|zsh|powershell>
+
+Arguments:
+ <bash|fish|nu|zsh|powershell>
+ Shell to generate code for
+
+ [possible values: bash, fish, nu, zsh, powershell]
+
+Options:
+ --cmd <CMD>
+ Command name for shell integration (defaults to binary name)
+
+ Use this to create shell integration for an alternate command name. For example,
+ --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt
+ conflicts with Windows Terminal.
+
+ -h, --help
+ Print help (see a summary with '-h')
+```
+
+## wt config shell install
+
+Write shell integration to config files.
+
+Appends an initialization line to bash, zsh, and PowerShell config files. For fish and Nushell, it replaces the autoloaded wrapper file; fish also gets a separate completion file. See [worktrunk.dev/shell-integration](https://worktrunk.dev/shell-integration/#files-created) for their locations.
+
+### Examples
+
+Install for all detected shells:
+```console
+$ wt config shell install
+```
+
+Install for specific shell only:
+```console
+$ wt config shell install zsh
+```
+
+Shows proposed changes and waits for confirmation before modifying any files.
+Use --yes to skip confirmation.
+
+### Command reference
+
+```
+wt config shell install - Write shell integration to config files
+
+Usage: wt config shell install [OPTIONS] [bash|fish|nu|zsh|powershell]
+
+Arguments:
+ [bash|fish|nu|zsh|powershell]
+ Shell to install (default: all)
+
+ [possible values: bash, fish, nu, zsh, powershell]
+
+Options:
+ --dry-run
+ Show what would be changed
+
+ --cmd <CMD>
+ Command name for shell integration (defaults to binary name)
+
+ Use this to create shell integration for an alternate command name. For example,
+ --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt
+ conflicts with Windows Terminal.
+
+ -h, --help
+ Print help (see a summary with '-h')
+```
+
+## wt config shell uninstall
+
+Remove shell integration from config files.
+
+Removes Worktrunk initialization lines from bash, zsh, and PowerShell config files, and Worktrunk wrapper and completion files for fish and Nushell.
+
+### Examples
+
+Uninstall from all shells:
+```console
+$ wt config shell uninstall
+```
+
+Uninstall from specific shell only:
+```console
+$ wt config shell uninstall zsh
+```
+
+Skip confirmation prompt:
+```console
+$ wt config shell uninstall --yes
+```
+
+### Version tolerance
+
+Uninstall removes every worktrunk-managed integration it finds, regardless of:
+- Binary name it was installed under (`wt`, `git-wt`, …)
+- Minor syntax variations between versions
+
+### Command reference
+
+```
+wt config shell uninstall - Remove shell integration from config files
+
+Usage: wt config shell uninstall [OPTIONS] [bash|fish|nu|zsh|powershell]
+
+Arguments:
+ [bash|fish|nu|zsh|powershell]
+ Shell to uninstall (default: all)
+
+ [possible values: bash, fish, nu, zsh, powershell]
+
+Options:
+ --dry-run
+ Show what would be changed
+
+ -h, --help
+ Print help (see a summary with '-h')
+```
+
## wt config show
Show configuration files & locations.
diff --git a/skills/worktrunk/reference/shell-integration.md b/skills/worktrunk/reference/shell-integration.md
index f259d49e8..5b0d33b33 100644
--- a/skills/worktrunk/reference/shell-integration.md
+++ b/skills/worktrunk/reference/shell-integration.md
@@ -1,62 +1,34 @@
# Shell integration
-Shell integration is what lets `wt switch` change your shell's directory. This page covers how it works, what it installs, and how to fix it when it doesn't.
+[`wt config shell`](https://worktrunk.dev/config/#wt-config-shell) covers setup, activation, and current-shell diagnostics. This guide covers installed files, warning messages, and wrapper behavior.
## Why shell integration exists
-A subprocess cannot change its parent shell's directory. When `wt switch feature` runs, the `wt` binary is a child process and cannot `cd` the terminal.
-
-Worktrunk solves this with a file directive: the shell wrapper creates one temp file, `wt` writes the target directory to it, and the wrapper changes directory after `wt` exits. `--execute` runs directly inside `wt`. See [How the shell wrapper works](#how-the-shell-wrapper-works) for the steps and a simplified implementation.
+The [shell integration overview](https://worktrunk.dev/config/#wt-config-shell) explains why directory switching needs a shell function. [How the shell wrapper works](#how-the-shell-wrapper-works) describes the directive mechanism.
## Installation
-```bash
-# Auto-install for all shells (bash, zsh, fish, nushell (experimental), PowerShell)
-wt config shell install
-
-# Or manual installation - add to the shell config:
-# bash (~/.bashrc):
-eval "$(wt config shell init bash)"
-
-# zsh (~/.zshrc):
-eval "$(wt config shell init zsh)"
-
-# fish (~/.config/fish/config.fish):
-wt config shell init fish | source
-
-# nushell 0.113+ (experimental) — save to vendor autoload directory:
-wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join wt.nu)
-
-# PowerShell ($PROFILE):
-Invoke-Expression (& wt config shell init powershell | Out-String)
-```
+See [`wt config shell install`](https://worktrunk.dev/config/#wt-config-shell-install) for automatic installation and [`wt config shell init`](https://worktrunk.dev/config/#wt-config-shell-init) for manual setup in each supported shell.
## Files created
-`wt config shell install` writes:
+[`wt config shell install`](https://worktrunk.dev/config/#wt-config-shell-install) uses these locations:
-- **Bash**: adds a line to `~/.bashrc`
-- **Zsh**: adds a line to `~/.zshrc` (or `$ZDOTDIR/.zshrc`)
-- **Fish**: creates `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish` (under `$XDG_CONFIG_HOME/fish` when that is set)
-- **Nushell 0.113+** [experimental]: creates `wt.nu` in Nushell's user vendor-autoload directory — the last entry of `$nu.vendor-autoload-dirs`, under `$nu.data-dir` (typically `~/.local/share/nushell/vendor/autoload` on Linux, `~/Library/Application Support/nushell/vendor/autoload` on macOS)
-- **PowerShell** (Windows): creates both profile files if they don't exist:
+- **Bash**: `~/.bashrc`
+- **Zsh**: `~/.zshrc` (or `$ZDOTDIR/.zshrc`)
+- **Fish**: `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish` (under `$XDG_CONFIG_HOME/fish` when that is set)
+- **Nushell 0.113+** [experimental]: `wt.nu` in Nushell's user vendor-autoload directory — the last entry of `$nu.vendor-autoload-dirs`, under `$nu.data-dir` (typically `~/.local/share/nushell/vendor/autoload` on Linux, `~/Library/Application Support/nushell/vendor/autoload` on macOS)
+- **PowerShell** (Windows): both profile files:
- `Documents/PowerShell/Microsoft.PowerShell_profile.ps1` (PowerShell 7+)
- `Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1` (Windows PowerShell 5.1)
-Fish and Nushell wrappers live at a path named after the command, so install writes that file whole, replacing an existing `functions/wt.fish`, `completions/wt.fish`, or `wt.nu`. Bash, zsh, and PowerShell rc files hold the rest of a shell's setup, so install only appends a line to those.
-
**PowerShell detection on Windows:** When running from cmd.exe or PowerShell, both PowerShell profile files are created automatically. When running from Git Bash or MSYS2, PowerShell is skipped (use `wt config shell install powershell` to create the profiles explicitly).
-**To remove:** `wt config shell uninstall`.
+See [`wt config shell uninstall`](https://worktrunk.dev/config/#wt-config-shell-uninstall) for removal.
## Checking status
-```bash
-# Show shell integration status
-wt config show
-```
-
-The RUNTIME section shows whether shell integration is active for the current session.
+The [current-shell checks](https://worktrunk.dev/config/#wt-config-shell) explain how to inspect installation and activation with `wt config show` and the shell's command lookup.
## Warning messages
@@ -70,9 +42,9 @@ When shell integration isn't working, `wt switch` shows a warning explaining why
### "shell integration not installed"
-**Meaning**: The current shell's config file doesn't have the `eval "$(wt config shell init ...)"` line. The current shell is detected from the process tree (falling back to `$SHELL`), so this refers to the shell `wt` was actually invoked from, not necessarily the login shell.
+**Meaning**: The current shell has no installed Worktrunk initialization line or wrapper file. The current shell is detected from the process tree (falling back to `$SHELL`), so this refers to the shell `wt` was actually invoked from, not necessarily the login shell.
-**Fix**: Run `wt config shell install` or add the line manually.
+**Fix**: Run `wt config shell install` or follow the [manual setup](https://worktrunk.dev/config/#wt-config-shell-init).
### "shell integration installed but not active"
@@ -189,11 +161,11 @@ grep -n "wt config shell init" ~/.bashrc
# zsh
grep -n "wt config shell init" ~/.zshrc
-# fish
+# fish (manual setup)
grep -n "wt config shell init" ~/.config/fish/config.fish
```
-This should show the `eval` line with its line number.
+These commands show the initialization line and its line number. `wt config shell install` writes fish and Nushell wrapper files instead; check those at the locations listed under [Files created](#files-created).
### 4. Check whether directive files are set
diff --git a/src/cli/config.rs b/src/cli/config.rs
index 05c7f8c4b..09634b451 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -33,7 +33,7 @@ pub enum ConfigShellCommand {
## Manual setup
-Add one line to the shell config:
+For bash, fish, zsh, and PowerShell, add the matching line to the shell config. For Nushell, run the command to save the wrapper in its autoload directory.
Bash (~/.bashrc):
```console
@@ -53,6 +53,11 @@ eval "$(wt config shell init zsh)"
Nushell 0.113+ [experimental] — save to vendor autoload directory:
```console
$ wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join wt.nu)
+```
+
+PowerShell ($PROFILE):
+```powershell
+Invoke-Expression (& wt config shell init powershell | Out-String)
```"#
)]
Init {
@@ -71,7 +76,7 @@ $ wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join
/// Write shell integration to config files
#[command(
- after_long_help = r#"Detects existing shell config files and adds the integration line.
+ after_long_help = r#"Appends an initialization line to bash, zsh, and PowerShell config files. For fish and Nushell, it replaces the autoloaded wrapper file; fish also gets a separate completion file. See [worktrunk.dev/shell-integration](/shell-integration/#files-created) for their locations.
## Examples
@@ -108,7 +113,7 @@ Use --yes to skip confirmation."#
/// Remove shell integration from config files
#[command(
- after_long_help = r#"Removes shell integration lines from config files.
+ after_long_help = r#"Removes Worktrunk initialization lines from bash, zsh, and PowerShell config files, and Worktrunk wrapper and completion files for fish and Nushell.
## Examples
@@ -626,6 +631,36 @@ $ wt config alias dry-run deploy -- --env=staging
#[derive(Subcommand)]
pub enum ConfigCommand {
/// Shell integration setup
+ #[command(
+ after_long_help = r#"A subprocess cannot change its parent shell's directory. Shell integration defines a function that runs the Worktrunk binary, then changes the shell's directory when the command requests it. It also enables tab completion.
+
+## Setup
+
+```console
+$ wt config shell install
+```
+
+Start a new shell after installation to load the wrapper. Invoke `wt` by name. Running a binary path or `git wt` bypasses the wrapper, so the shell's directory stays unchanged.
+
+- `wt config shell install --help` — installation options
+- `wt config shell init --help` — manual setup
+- `wt config shell uninstall` — remove the integration
+
+## Check the current shell
+
+```console
+$ wt config show
+```
+
+The SHELL INTEGRATION section reports whether the wrapper is active in the current session. Installation and activation are separate: a configured shell can still be running without the wrapper until its config is reloaded.
+
+In bash, zsh, or fish, `type wt` checks that `wt` resolves to a function. In PowerShell, `Get-Command wt -All` lists the Function and Application definitions.
+
+See [worktrunk.dev/shell-integration](/shell-integration/) for warning messages, installed files, and wrapper behavior.
+<!-- subdoc: init -->
+<!-- subdoc: install -->
+<!-- subdoc: uninstall -->"#
+ )]
Shell {
#[command(subcommand)]
action: ConfigShellCommand,
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index e0907554e..303a6f6ad 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -2584,15 +2584,7 @@ Aliases defined here are shared with teammates. For personal aliases, use the [u
# Shell Integration
-Worktrunk needs shell integration to change directories when switching worktrees. Install with:
-
-```console
-$ wt config shell install
-```
-
-For manual setup, see `wt config shell init --help`.
-
-Without shell integration, `wt switch` prints the target directory but cannot `cd` into it.
+See [`wt config shell`](#wt-config-shell) for setup, activation, and current-shell diagnostics.
### First-run prompts
@@ -2665,6 +2657,7 @@ $ wt --config-set 'projects."github.com/owner/repo".worktree-path = "/tmp/scratc
```
Hooks, aliases and `step.copy-ignored.exclude` accumulate rather than replace, so an env-set hook and a project's hook both run.
+<!-- subdoc: shell -->
<!-- subdoc: show -->
<!-- subdoc: update -->
<!-- subdoc: approvals -->
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index cd6c5ef7d..d0c672e66 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -598,13 +598,7 @@ Aliases defined here are shared with teammates. For personal aliases, use the us
SHELL INTEGRATION
-Worktrunk needs shell integration to change directories when switching worktrees. Install with:
-
-  wt config shell install
-
-For manual setup, see wt config shell init --help.
-
-Without shell integration, wt switch prints the target directory but cannot cd into it.
+See wt config shell for setup, activation, and current-shell diagnostics.
First-run prompts
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_shell.snap b/tests/snapshots/integration__integration_tests__help__help_config_shell.snap
index f1871a972..d65d75610 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_shell.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_shell.snap
@@ -54,13 +54,45 @@ Usage: wt config shell [OPTIONS] <COMMAND>
show-theme Show output theme samples
Options:
- -h, --help Print help
+ -h, --help
+ Print help (see a summary with '-h')
Global Options:
- -C <path> Working directory for this command
- --config <path> User config file path
- --config-set <toml> Override config with inline TOML, e.g. --config-set list.full=true (repeatable)
- -v, --verbose... Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to apply the same level everywhere — including shell completion, which no flag can reach
- -y, --yes Skip approval prompts
+ -C <path>
+ Working directory for this command
+
+ --config <path>
+ User config file path
+
+ --config-set <toml>
+ Override config with inline TOML, e.g. --config-set list.full=true (repeatable)
+
+ -v, --verbose...
+ Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to apply the same level everywhere — including shell completion, which no flag can reach
+
+ -y, --yes
+ Skip approval prompts
+
+A subprocess cannot change its parent shell's directory. Shell integration defines a function that runs the Worktrunk binary, then changes the shell's directory when the command requests it. It also enables tab completion.
+
+Setup
+
+  wt config shell install
+
+Start a new shell after installation to load the wrapper. Invoke wt by name. Running a binary path or git wt bypasses the wrapper, so the shell's directory stays unchanged.
+
+- wt config shell install --help — installation options
+- wt config shell init --help — manual setup
+- wt config shell uninstall — remove the integration
+
+Check the current shell
+
+  wt config show
+
+The SHELL INTEGRATION section reports whether the wrapper is active in the current session. Installation and activation are separate: a configured shell can still be running without the wrapper until its config is reloaded.
+
+In bash, zsh, or fish, type wt checks that wt resolves to a function. In PowerShell, Get-Command wt -All lists the Function and Application definitions.
+
+See worktrunk.dev/shell-integration for warning messages, installed files, and wrapper behavior.
----- stderr -----