Skip to content

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

Document environment variable config overrides

Maximilian Roos8e6c34dd1cc9
diff --git a/.claude-plugin/skills/worktrunk/reference/user-config.md b/.claude-plugin/skills/worktrunk/reference/user-config.md
index f6184d569..6c55f1703 100644
--- a/.claude-plugin/skills/worktrunk/reference/user-config.md
+++ b/.claude-plugin/skills/worktrunk/reference/user-config.md
@@ -261,6 +261,23 @@ wt config --help # Show LLM setup guide
- **macOS/Linux**: `~/.config/worktrunk/config.toml` (or `$XDG_CONFIG_HOME/worktrunk/config.toml`)
- **Windows**: `%APPDATA%\worktrunk\config.toml`
+## Environment Variable Overrides
+
+All config options can be overridden via environment variables with the `WORKTRUNK_` prefix:
+
+- Single underscore after prefix: `WORKTRUNK_WORKTREE_PATH`
+- Double underscore for nested keys: `WORKTRUNK_COMMIT_GENERATION__COMMAND`
+- Snake_case env vars convert to kebab-case config keys automatically
+
+```bash
+# Override LLM in CI/testing
+WORKTRUNK_COMMIT_GENERATION__COMMAND=echo \
+WORKTRUNK_COMMIT_GENERATION__ARGS="test: mock commit" \
+ wt merge
+```
+
+Array values like `args` can be specified as single strings in env vars.
+
## Example Config
See `dev/config.example.toml` in the worktrunk repository for a complete annotated example.
diff --git a/docs/content/configuration.md b/docs/content/configuration.md
index b012db184..cfb4b5820 100644
--- a/docs/content/configuration.md
+++ b/docs/content/configuration.md
@@ -138,8 +138,44 @@ Without shell integration, `wt switch` prints the target directory but cannot `c
## Environment Variables
+All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.
+
+### Naming convention
+
+Config keys use kebab-case (`worktree-path`), while env vars use SCREAMING_SNAKE_CASE (`WORKTRUNK_WORKTREE_PATH`). The conversion happens automatically.
+
+For nested config sections, use double underscores to separate levels:
+
+| Config | Environment Variable |
+|--------|---------------------|
+| `worktree-path` | `WORKTRUNK_WORKTREE_PATH` |
+| `commit-generation.command` | `WORKTRUNK_COMMIT_GENERATION__COMMAND` |
+| `commit-generation.args` | `WORKTRUNK_COMMIT_GENERATION__ARGS` |
+
+Note the single underscore after `WORKTRUNK` and double underscores between nested keys.
+
+### Array values
+
+Array config values like `args = ["-m", "claude-haiku"]` can be specified as a single string in environment variables:
+
+```bash
+export WORKTRUNK_COMMIT_GENERATION__ARGS="-m claude-haiku"
+```
+
+### Example: CI/testing override
+
+Override the LLM command in CI to use a mock:
+
+```bash
+WORKTRUNK_COMMIT_GENERATION__COMMAND=echo \
+WORKTRUNK_COMMIT_GENERATION__ARGS="test: automated commit" \
+ wt merge
+```
+
+### Special variables
+
| Variable | Purpose |
|----------|---------|
-| `WORKTRUNK_CONFIG_PATH` | Override user config location |
+| `WORKTRUNK_CONFIG_PATH` | Override user config file location (not a config key) |
| `NO_COLOR` | Disable colored output ([standard](https://no-color.org/)) |
| `CLICOLOR_FORCE` | Force colored output even when not a TTY |