Skip to content

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

Smart routing for alias arguments + dry-run routing display (#2304)

Maximilian Roos68229ce57199
diff --git a/docs/content/extending.md b/docs/content/extending.md
index fe1a6ab66..a495dac9b 100644
--- a/docs/content/extending.md
+++ b/docs/content/extending.md
@@ -108,85 +108,52 @@ See [Tips & Patterns](@/tips-patterns.md) for more recipes: dev server per workt
## Aliases
-Aliases are custom commands invoked as `wt <name>`. They share the same template variables and approval model as hooks.
+`[aliases]` defines commands invoked as `wt <name>`. Templates and approvals behave like hooks.
```toml
[aliases]
-deploy = "make deploy BRANCH={{ branch }} ENV={{ env }}"
+deploy = "fly deploy --config=fly.{{ env }}.toml --app=myapp-{{ branch }}"
open = "open http://localhost:{{ branch | hash_port }}"
+since-main = "git log --oneline {{ default_branch }}..HEAD"
```
-{{ terminal(cmd="wt deploy|||wt deploy --env=staging") }}
+{{ terminal(cmd="wt deploy --env=staging|||wt open") }}
-`wt deploy` resolves `deploy` against configured aliases first, then falls through to a `wt-deploy` PATH binary if no alias matches. Built-in subcommands always take precedence — an alias named `list` or `switch` is unreachable.
+`wt <name>` resolves to a built-in first, then an alias, then a [custom subcommand](#custom-subcommands).
-### How arguments are routed
+### Passing values
-Tokens after the alias name fall into one of these buckets, decided by what the alias's template references:
+`--KEY=VALUE` (or `--KEY VALUE`) binds `KEY` whenever `{{ KEY }}` appears in the template — `wt deploy --env=staging` sets `{{ env }}` to `staging`. Everything else joins `{{ args }}` (see [Forwarding](#forwarding-positional-arguments)).
-| Token shape | Routes to |
-|---|---|
-| `--KEY=VALUE` or `--KEY VALUE` where the template references `{{ KEY }}` | Bound — `KEY` becomes the template value |
-| `--KEY=VALUE` where the template doesn't reference `KEY` | Forwarded literally to `{{ args }}` |
-| `--KEY` followed by another flag or end of args | Forwarded literally to `{{ args }}` |
-| Bare positional (no `--` prefix) | Forwarded to `{{ args }}` |
-| Anything after a literal `--` | Forwarded to `{{ args }}` regardless of shape |
+Built-in variables can be overridden: `--branch=foo` sets `{{ branch }}` inside the template — the worktree's actual branch doesn't move.
-Built-in template variables (`branch`, `worktree_path`, `commit`, …) can be overridden — `--branch=override` for an alias referencing `{{ branch }}` binds to the user's value, but only inside the template; the worktree's actual branch is unchanged.
-
-Hyphens in variable names are canonicalized to underscores at parse time. `--my-var=value` binds to `{{ my_var }}` because minijinja parses `{{ my-var }}` as subtraction.
-
-### Escaping with `--`
-
-Use `--` to forward a flag-shaped value literally instead of letting the parser bind it. Everything after `--` goes into `{{ args }}` verbatim:
-
-```toml
-[aliases]
-search = "rg {{ args }}"
-```
-
-{{ terminal(cmd="wt search -- --hidden --glob '*.rs' pattern # --hidden and --glob reach rg, not the alias parser") }}
-
-### Inspecting and previewing
-
-Two subcommands introspect aliases without running them:
-
-- `wt config alias show <name>` prints the configured template text, tagged by source (`user`/`project`).
-- `wt config alias dry-run <name> [-- args...]` parses the invocation with the same parser `wt <name>` uses, then prints the rendered command without executing.
-
-{{ terminal(cmd="wt config alias show deploy|||wt config alias dry-run deploy|||wt config alias dry-run deploy -- --env=staging") }}
-
-Arguments after `--` in `dry-run` are forwarded verbatim — `wt config alias dry-run s -- target-branch` previews exactly what `wt s target-branch` would run. Templates referencing `vars.*` are shown unexpanded, mirroring execution semantics: those values are read from git config just before each step runs.
+Hyphens in keys become underscores: `--my-var=x` sets `{{ my_var }}`.
### Forwarding positional arguments
-Non-flag tokens after the alias name are forwarded to the template as `{{ args }}`. Bare `{{ args }}` renders as a space-joined, shell-escaped string ready to append to a command line — so `wt s some-branch` with `s = "wt switch {{ args }}"` expands to `wt switch some-branch`.
+`{{ args }}` renders as a space-joined, shell-escaped string — ready to splice into a command:
```toml
[aliases]
s = "wt switch {{ args }}"
```
-{{ terminal(cmd="wt s some-branch|||wt s feature/api # multiple tokens pass through in order|||wt s 'has a space' # spaces and metacharacters are escaped safely") }}
+{{ terminal(cmd="wt s some-branch|||wt s feature/api|||wt s 'has a space'") }}
-Access elements with `{{ args[0] }}`, iterate with `{% for a in args %}…{% endfor %}`, or count with `{{ args | length }}`. Each element is individually shell-escaped, so `wt run 'a b' 'c;d'` splices in as `'a b' 'c;d'` without shell injection.
+Index with `{{ args[0] }}`, loop with `{% for a in args %}…{% endfor %}`, count with `{{ args | length }}`. Each element is escaped individually, so `wt run 'a b' 'c;d'` renders as `'a b' 'c;d'` — no shell injection.
-An `up` alias that fetches all remotes and rebases each worktree onto its upstream:
+Tokens after `--` forward unconditionally, bypassing any binding. `wt deploy -- --branch=foo` forwards `--branch=foo` to `{{ args }}` even though the template references `{{ branch }}`.
-```toml
-[aliases]
-up = '''
-git fetch --all --prune && wt step for-each -- '
- git rev-parse --verify @{u} >/dev/null 2>&1 || exit 0
- g=$(git rev-parse --git-dir)
- test -d "$g/rebase-merge" -o -d "$g/rebase-apply" && exit 0
- git rebase @{u} --no-autostash || git rebase --abort
-''''
-```
+### Inspecting and previewing
+
+- `wt config alias show <name>` prints the template.
+- `wt config alias dry-run <name> [-- args...]` prints the rendered command.
+
+{{ terminal(cmd="wt config alias show deploy|||wt config alias dry-run deploy|||wt config alias dry-run deploy -- --env=staging") }}
### Multi-step pipelines
-Multi-step aliases run commands in order using `[[aliases.NAME]]` blocks. Each block is one step; multiple keys within a block run concurrently.
+`[[aliases.NAME]]` defines a pipeline. Each block runs serially; keys within a block run concurrently.
```toml
[[aliases.release]]
@@ -197,16 +164,31 @@ build = "cargo build --release"
package = "cargo package --no-verify"
[[aliases.release]]
-publish = "cargo publish"
+publish = "cargo publish {{ args }}"
```
-`test` runs first, then `build` and `package` run together, then `publish` runs last. A step failure aborts the remaining steps.
+`test` runs first, then `build` and `package` run together, then `publish` runs last. A step failure aborts the remaining steps. Every step sees the same `{{ args }}` and bound variables — `wt release -- --dry-run` forwards `--dry-run` to `publish` without affecting earlier steps.
### Sources and approval
When both user and project config define the same alias name, both run — user first, then project. Project-config aliases require approval on first run, same as project hooks. User-config aliases are trusted.
-Inside an alias body, an inner `wt switch` (or `wt switch --create`) passes its `cd` through to the parent shell, so an alias wrapping `wt switch --create` lands the shell in the new worktree just like running it directly.
+An alias that calls `wt switch` (or `wt switch --create`) changes the parent shell's directory, just like running `wt switch` directly.
+
+### Recipe: rebase every worktree onto its upstream
+
+```toml
+[aliases]
+up = '''
+git fetch --all --prune && wt step for-each -- '
+ git rev-parse --verify @{u} >/dev/null 2>&1 || exit 0
+ g=$(git rev-parse --git-dir)
+ test -d "$g/rebase-merge" -o -d "$g/rebase-apply" && exit 0
+ git rebase @{u} --no-autostash || git rebase --abort
+''''
+```
+
+`wt up` fetches all remotes, then iterates every worktree: skip if no upstream, skip if mid-rebase, otherwise rebase and auto-abort on conflict.
### Recipe: move or copy in-progress changes to a new worktree
diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.md
index 446c4db46..37d11df61 100644
--- a/skills/worktrunk/reference/extending.md
+++ b/skills/worktrunk/reference/extending.md
@@ -101,56 +101,53 @@ See [Tips & Patterns](https://worktrunk.dev/tips-patterns/) for more recipes: de
## Aliases
-Aliases are custom commands invoked as `wt <name>`. They share the same template variables and approval model as hooks.
+`[aliases]` defines commands invoked as `wt <name>`. Templates and approvals behave like hooks.
```toml
[aliases]
-deploy = "make deploy BRANCH={{ branch }} ENV={{ env }}"
+deploy = "fly deploy --config=fly.{{ env }}.toml --app=myapp-{{ branch }}"
open = "open http://localhost:{{ branch | hash_port }}"
+since-main = "git log --oneline {{ default_branch }}..HEAD"
```
```bash
-wt deploy
wt deploy --env=staging
+wt open
```
-`wt deploy` resolves `deploy` against configured aliases first, then falls through to a `wt-deploy` PATH binary if no alias matches. Built-in subcommands always take precedence — an alias named `list` or `switch` is unreachable.
+`wt <name>` resolves to a built-in first, then an alias, then a [custom subcommand](#custom-subcommands).
-### How arguments are routed
+### Passing values
-Tokens after the alias name fall into one of these buckets, decided by what the alias's template references:
+`--KEY=VALUE` (or `--KEY VALUE`) binds `KEY` whenever `{{ KEY }}` appears in the template — `wt deploy --env=staging` sets `{{ env }}` to `staging`. Everything else joins `{{ args }}` (see [Forwarding](#forwarding-positional-arguments)).
-| Token shape | Routes to |
-|---|---|
-| `--KEY=VALUE` or `--KEY VALUE` where the template references `{{ KEY }}` | Bound — `KEY` becomes the template value |
-| `--KEY=VALUE` where the template doesn't reference `KEY` | Forwarded literally to `{{ args }}` |
-| `--KEY` followed by another flag or end of args | Forwarded literally to `{{ args }}` |
-| Bare positional (no `--` prefix) | Forwarded to `{{ args }}` |
-| Anything after a literal `--` | Forwarded to `{{ args }}` regardless of shape |
+Built-in variables can be overridden: `--branch=foo` sets `{{ branch }}` inside the template — the worktree's actual branch doesn't move.
-Built-in template variables (`branch`, `worktree_path`, `commit`, …) can be overridden — `--branch=override` for an alias referencing `{{ branch }}` binds to the user's value, but only inside the template; the worktree's actual branch is unchanged.
+Hyphens in keys become underscores: `--my-var=x` sets `{{ my_var }}`.
-Hyphens in variable names are canonicalized to underscores at parse time. `--my-var=value` binds to `{{ my_var }}` because minijinja parses `{{ my-var }}` as subtraction.
-
-### Escaping with `--`
+### Forwarding positional arguments
-Use `--` to forward a flag-shaped value literally instead of letting the parser bind it. Everything after `--` goes into `{{ args }}` verbatim:
+`{{ args }}` renders as a space-joined, shell-escaped string — ready to splice into a command:
```toml
[aliases]
-search = "rg {{ args }}"
+s = "wt switch {{ args }}"
```
```bash
-wt search -- --hidden --glob '*.rs' pattern # --hidden and --glob reach rg, not the alias parser
+wt s some-branch
+wt s feature/api
+wt s 'has a space'
```
-### Inspecting and previewing
+Index with `{{ args[0] }}`, loop with `{% for a in args %}…{% endfor %}`, count with `{{ args | length }}`. Each element is escaped individually, so `wt run 'a b' 'c;d'` renders as `'a b' 'c;d'` — no shell injection.
+
+Tokens after `--` forward unconditionally, bypassing any binding. `wt deploy -- --branch=foo` forwards `--branch=foo` to `{{ args }}` even though the template references `{{ branch }}`.
-Two subcommands introspect aliases without running them:
+### Inspecting and previewing
-- `wt config alias show <name>` prints the configured template text, tagged by source (`user`/`project`).
-- `wt config alias dry-run <name> [-- args...]` parses the invocation with the same parser `wt <name>` uses, then prints the rendered command without executing.
+- `wt config alias show <name>` prints the template.
+- `wt config alias dry-run <name> [-- args...]` prints the rendered command.
```bash
wt config alias show deploy
@@ -158,41 +155,9 @@ wt config alias dry-run deploy
wt config alias dry-run deploy -- --env=staging
```
-Arguments after `--` in `dry-run` are forwarded verbatim — `wt config alias dry-run s -- target-branch` previews exactly what `wt s target-branch` would run. Templates referencing `vars.*` are shown unexpanded, mirroring execution semantics: those values are read from git config just before each step runs.
-
-### Forwarding positional arguments
-
-Non-flag tokens after the alias name are forwarded to the template as `{{ args }}`. Bare `{{ args }}` renders as a space-joined, shell-escaped string ready to append to a command line — so `wt s some-branch` with `s = "wt switch {{ args }}"` expands to `wt switch some-branch`.
-
-```toml
-[aliases]
-s = "wt switch {{ args }}"
-```
-
-```bash
-wt s some-branch
-wt s feature/api # multiple tokens pass through in order
-wt s 'has a space' # spaces and metacharacters are escaped safely
-```
-
-Access elements with `{{ args[0] }}`, iterate with `{% for a in args %}…{% endfor %}`, or count with `{{ args | length }}`. Each element is individually shell-escaped, so `wt run 'a b' 'c;d'` splices in as `'a b' 'c;d'` without shell injection.
-
-An `up` alias that fetches all remotes and rebases each worktree onto its upstream:
-
-```toml
-[aliases]
-up = '''
-git fetch --all --prune && wt step for-each -- '
- git rev-parse --verify @{u} >/dev/null 2>&1 || exit 0
- g=$(git rev-parse --git-dir)
- test -d "$g/rebase-merge" -o -d "$g/rebase-apply" && exit 0
- git rebase @{u} --no-autostash || git rebase --abort
-''''
-```
-
### Multi-step pipelines
-Multi-step aliases run commands in order using `[[aliases.NAME]]` blocks. Each block is one step; multiple keys within a block run concurrently.
+`[[aliases.NAME]]` defines a pipeline. Each block runs serially; keys within a block run concurrently.
```toml
[[aliases.release]]
@@ -203,16 +168,31 @@ build = "cargo build --release"
package = "cargo package --no-verify"
[[aliases.release]]
-publish = "cargo publish"
+publish = "cargo publish {{ args }}"
```
-`test` runs first, then `build` and `package` run together, then `publish` runs last. A step failure aborts the remaining steps.
+`test` runs first, then `build` and `package` run together, then `publish` runs last. A step failure aborts the remaining steps. Every step sees the same `{{ args }}` and bound variables — `wt release -- --dry-run` forwards `--dry-run` to `publish` without affecting earlier steps.
### Sources and approval
When both user and project config define the same alias name, both run — user first, then project. Project-config aliases require approval on first run, same as project hooks. User-config aliases are trusted.
-Inside an alias body, an inner `wt switch` (or `wt switch --create`) passes its `cd` through to the parent shell, so an alias wrapping `wt switch --create` lands the shell in the new worktree just like running it directly.
+An alias that calls `wt switch` (or `wt switch --create`) changes the parent shell's directory, just like running `wt switch` directly.
+
+### Recipe: rebase every worktree onto its upstream
+
+```toml
+[aliases]
+up = '''
+git fetch --all --prune && wt step for-each -- '
+ git rev-parse --verify @{u} >/dev/null 2>&1 || exit 0
+ g=$(git rev-parse --git-dir)
+ test -d "$g/rebase-merge" -o -d "$g/rebase-apply" && exit 0
+ git rebase @{u} --no-autostash || git rebase --abort
+''''
+```
+
+`wt up` fetches all remotes, then iterates every worktree: skip if no upstream, skip if mid-rebase, otherwise rebase and auto-abort on conflict.
### Recipe: move or copy in-progress changes to a new worktree
diff --git a/src/cli/config.rs b/src/cli/config.rs
index ceba5b6c6..73ebe52c4 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -330,7 +330,7 @@ $ wt config alias show deploy
/// Preview an alias invocation with template expansion
#[command(
- after_long_help = r#"Runs the same parser used at invocation time, applies template expansion (including `{{ args }}` and any `--var`/`--KEY=VALUE` assignments), and prints the resulting command without executing it. Templates referencing `vars.*` are shown unexpanded — those values resolve from git config at execution time, after earlier steps have had a chance to set them.
+ after_long_help = r#"Runs the same parser used at invocation time, applies template expansion (including `{{ args }}` and any `--KEY=VALUE` assignments), and prints the resulting command without executing it. Templates referencing `vars.*` are shown unexpanded — those values resolve from git config at execution time, after earlier steps have had a chance to set them.
Arguments after `--` are forwarded verbatim as if typed after `wt <name>`.
diff --git a/src/cli/hook.rs b/src/cli/hook.rs
index 549ff4df1..bf75c849f 100644
--- a/src/cli/hook.rs
+++ b/src/cli/hook.rs
@@ -37,8 +37,10 @@ const KNOWN_HOOK_LONG_FLAGS: &[&str] = &[
];
/// Rewrite `wt hook <type> --KEY=VALUE` into `wt hook <type> --var KEY=VALUE`
-/// for unknown `--key=value` flags, matching the ergonomics of the alias
-/// variable shorthand (see `AliasOptions::parse`).
+/// for unknown `--key=value` flags, so hook invocations can use the same
+/// `--KEY=VALUE` shorthand that `wt <alias>` supports. (Aliases route via
+/// template references; hooks have no such discriminator, so the rewrite
+/// here is an unconditional "unknown `--KEY=VALUE` means var".)
///
/// Only args after a `hook <type>` prefix are touched, and only when `<type>`
/// is a hook that accepts `--var`.
diff --git a/src/commands/alias.rs b/src/commands/alias.rs
index ebf1f5788..e2833dafc 100644
--- a/src/commands/alias.rs
+++ b/src/commands/alias.rs
@@ -40,7 +40,7 @@ use worktrunk::config::{
referenced_vars_for_config,
};
use worktrunk::git::Repository;
-use worktrunk::styling::{eprintln, progress_message};
+use worktrunk::styling::{eprintln, println, progress_message, warning_message};
use crate::commands::command_approval::approve_alias_commands;
use crate::commands::command_executor::{
@@ -72,19 +72,49 @@ const BUILTIN_STEP_COMMANDS: &[&str] = &[
/// alias dispatch sees the name, so `wt list` always runs the built-in even
/// if `[aliases] list = …` is configured. Kept in sync with `Cli` via
/// `test_top_level_builtins_match_clap`.
-const TOP_LEVEL_BUILTINS: &[&str] = &[
+pub(crate) const TOP_LEVEL_BUILTINS: &[&str] = &[
"config", "hook", "list", "merge", "remove", "select", "step", "switch",
];
+/// Whether `--help` or `-h` appears in `args` before any `--` literal-forward
+/// terminator. Aliases have no clap-style help page — the template *is* the
+/// help — so dispatchers intercept help requests and redirect the user to
+/// `wt config alias show / dry-run`. After `--`, all tokens forward to
+/// `{{ args }}` verbatim, so `wt <alias> -- --help` bypasses the intercept.
+fn help_flag_requested(args: &[String]) -> bool {
+ for arg in args {
+ if arg == "--" {
+ return false;
+ }
+ if arg == "--help" || arg == "-h" {
+ return true;
+ }
+ }
+ false
+}
+
+/// Print guidance when `wt <alias> --help` is invoked. Points at the canonical
+/// inspection path and documents the `--` escape for forwarding `--help` into
+/// the alias body.
+fn emit_alias_help_hint(name: &str) {
+ println!(
+ "`{name}` is an alias. Inspect with:
+ wt config alias show {name}
+ wt config alias dry-run {name}
+Forward `--help` to the alias body with `wt {name} -- --help`."
+ );
+}
+
/// Options parsed from alias-dispatch args (`wt step <alias>` or `wt <alias>`).
#[derive(Debug)]
pub struct AliasOptions {
pub name: String,
pub vars: Vec<(String, String)>,
- /// Non-flag positional tokens passed after the alias name. Forwarded into
- /// the template context as `{{ args }}` (a `ShellArgs` sequence). Appear
- /// in CLI order, interleaving freely with flags: `wt s foo --env=prod bar`
- /// collects `["foo", "bar"]`.
+ /// Tokens forwarded to the template as `{{ args }}` (a `ShellArgs`
+ /// sequence). Contains plain positionals, `--KEY=VALUE` / `--KEY` tokens
+ /// whose key isn't referenced by the template, and everything after `--`.
+ /// Appears in CLI order: `wt s foo --env=prod bar` with no `{{ env }}`
+ /// reference collects `["foo", "--env=prod", "bar"]`.
pub positional_args: Vec<String>,
}
@@ -98,14 +128,14 @@ impl AliasOptions {
///
/// - `--` — literal-forward escape: every later token goes straight into
/// `positional_args`, no var binding.
- /// - `--KEY=VALUE` — binds `KEY=VALUE` if `KEY` is in `referenced_vars`,
- /// otherwise forwards the whole `--KEY=VALUE` token as a positional.
- /// - `--KEY VALUE` (separated by space, `VALUE` doesn't start with `--`)
- /// — binds `KEY=VALUE` if `KEY` is in `referenced_vars`, otherwise
- /// forwards `--KEY` as a positional and re-examines `VALUE` at its
- /// normal position.
- /// - `--KEY` followed by another `--…` (or end of args) — forwards
- /// `--KEY` as a positional.
+ /// - `--KEY=VALUE` or `--KEY VALUE` — binds `KEY=VALUE` if `KEY` is in
+ /// `referenced_vars`, otherwise forwards both parts as positionals. The
+ /// space form consumes the next token as the value unconditionally —
+ /// even when it starts with `--` — so `--env --other` with `env`
+ /// referenced binds `env=--other`. Use the `=` form or put flags
+ /// before the bound key to avoid this.
+ /// - `--KEY` at end of args — forwards `--KEY` as a positional. No next
+ /// token to consume.
/// - Anything else — forwards as a positional.
///
/// `--yes`/`-y` is a top-level global flag (`wt -y <alias>`); the
@@ -129,13 +159,20 @@ impl AliasOptions {
/// `referenced_vars` is expected to contain the canonical underscore
/// form. `referenced_vars_for_config` produces it directly from the
/// alias's template.
- pub fn parse(args: Vec<String>, referenced_vars: &BTreeSet<String>) -> anyhow::Result<Self> {
+ ///
+ /// Returns `(options, warnings)`. Warnings are advisory — callers emit
+ /// them; the parser stays pure so tests can inspect both halves.
+ pub fn parse(
+ args: Vec<String>,
+ referenced_vars: &BTreeSet<String>,
+ ) -> anyhow::Result<(Self, Vec<String>)> {
let Some(name) = args.first().cloned() else {
bail!("Missing alias name");
};
let mut vars = Vec::new();
let mut positional_args = Vec::new();
+ let mut warnings = Vec::new();
let mut literal_mode = false;
let mut i = 1;
while i < args.len() {
@@ -169,17 +206,32 @@ impl AliasOptions {
i += 1;
continue;
}
+ // Bare `--KEY`: mirror the atomic `--KEY=VALUE` form. When a
+ // next token exists, consume both regardless of its shape —
+ // bind if KEY is referenced, else forward both as positionals.
+ // At end of args, forward `--KEY` alone.
let canon = rest.replace('-', "_");
- if let Some(next) = args.get(i + 1)
- && !next.starts_with("--")
- && referenced_vars.contains(&canon)
- {
- vars.push((canon, next.clone()));
+ if let Some(next) = args.get(i + 1) {
+ if referenced_vars.contains(&canon) {
+ // Warn on the footgun case: `--KEY --VALUE` with KEY
+ // referenced binds VALUE as the value. Almost always
+ // a typo — the user probably meant `--KEY=--VALUE`.
+ // Show the user's typed form (hyphenated) throughout;
+ // the template binding (underscored) is internal.
+ // Mirrors the `--var` TODO in hook_commands.rs.
+ if next.starts_with("--") {
+ warnings.push(format!(
+ "`--{rest} {next}` bound `{rest}` to `{next}` — use `--{rest}={next}` if that was intended"
+ ));
+ }
+ vars.push((canon, next.clone()));
+ } else {
+ positional_args.push(arg.clone());
+ positional_args.push(next.clone());
+ }
i += 2;
continue;
}
- // No bindable destination: forward the flag token as positional;
- // the next token is re-examined at its normal position.
positional_args.push(arg.clone());
i += 1;
continue;
@@ -188,11 +240,14 @@ impl AliasOptions {
i += 1;
}
- Ok(Self {
- name,
- vars,
- positional_args,
- })
+ Ok((
+ Self {
+ name,
+ vars,
+ positional_args,
+ },
+ warnings,
+ ))
}
}
@@ -316,11 +371,28 @@ pub fn try_alias(name: String, rest: Vec<String>, global_yes: bool) -> anyhow::R
return Ok(None);
};
let referenced = referenced_vars_for_config(cmd_config)?;
+ // Aliases can bind a `help` variable; only intercept `--help` when the
+ // template doesn't reference it. `-h` is never a binding, so it's always
+ // safe to intercept. Conservatively: intercept if any help flag appears
+ // and no binding is claimed on `help`.
+ if !referenced.contains("help") && help_flag_requested(&rest) {
+ emit_alias_help_hint(&name);
+ return Ok(Some(()));
+ }
let mut alias_args = Vec::with_capacity(1 + rest.len());
alias_args.push(name);
alias_args.extend(rest);
- let opts = AliasOptions::parse(alias_args, &referenced)?;
- run_alias(opts, repo, user_config, project_config, aliases, global_yes).map(Some)
+ let (opts, warnings) = AliasOptions::parse(alias_args, &referenced)?;
+ run_alias(
+ opts,
+ warnings,
+ repo,
+ user_config,
+ project_config,
+ aliases,
+ global_yes,
+ )
+ .map(Some)
}
/// Run a configured alias from `wt step <name>`. Errors with a clap-style
@@ -333,6 +405,11 @@ pub fn try_alias(name: String, rest: Vec<String>, global_yes: bool) -> anyhow::R
///
/// `global_yes` is the top-level `--yes`/`-y` flag, passed through to
/// `run_alias`.
+///
+/// TODO: consider deprecating `wt step <alias>` in favor of top-level
+/// `wt <alias>` (and `wt config alias show/dry-run` for inspection). The step
+/// path exists today as the escape for shadowed names, but that could instead
+/// be handled with a dedicated error hint.
pub fn step_alias(args: Vec<String>, global_yes: bool) -> anyhow::Result<()> {
let repo = Repository::current()?;
let user_config = UserConfig::load()?;
@@ -356,8 +433,20 @@ pub fn step_alias(args: Vec<String>, global_yes: bool) -> anyhow::Result<()> {
unknown_step_command_exit(&name, &alias_names);
};
let referenced = referenced_vars_for_config(cmd_config)?;
- let opts = AliasOptions::parse(args, &referenced)?;
- run_alias(opts, repo, user_config, project_config, aliases, global_yes)
+ if !referenced.contains("help") && help_flag_requested(&args[1..]) {
+ emit_alias_help_hint(&name);
+ return Ok(());
+ }
+ let (opts, warnings) = AliasOptions::parse(args, &referenced)?;
+ run_alias(
+ opts,
+ warnings,
+ repo,
+ user_config,
+ project_config,
+ aliases,
+ global_yes,
+ )
}
/// Return alias names for use as suggestions when a top-level subcommand is
@@ -388,6 +477,7 @@ pub fn alias_names_for_suggestions() -> Vec<String> {
/// recognized. Use `wt -y deploy` or `wt --yes deploy` instead.
fn run_alias(
opts: AliasOptions,
+ warnings: Vec<String>,
repo: Repository,
user_config: UserConfig,
project_config: Option<ProjectConfig>,
@@ -398,6 +488,12 @@ fn run_alias(
.get(&opts.name)
.expect("caller verified alias is configured");
+ // Surface parser advisories (e.g. `--KEY --VALUE` footgun) before
+ // announcing the run so they're visible in execution output.
+ for warning in &warnings {
+ eprintln!("{}", warning_message(warning));
+ }
+
// Check if this alias needs project-config approval. project_id is required
// for approval — re-derive with error propagation rather than relying on
// `.ok()`. `global_yes` is the sole source for skipping approval now that
@@ -724,7 +820,17 @@ mod tests {
/// Parse with an explicit `referenced_vars` set. Tests build the set
/// directly to exercise routing without needing a full template fixture.
+ /// Drops warnings — see `parse_with_warnings` to inspect them.
fn parse_with(args: &[&str], referenced: &[&str]) -> anyhow::Result<AliasOptions> {
+ parse_with_warnings(args, referenced).map(|(opts, _)| opts)
+ }
+
+ /// Like `parse_with` but also returns the warning vector, for tests that
+ /// assert on advisory output.
+ fn parse_with_warnings(
+ args: &[&str],
+ referenced: &[&str],
+ ) -> anyhow::Result<(AliasOptions, Vec<String>)> {
let refs: BTreeSet<String> = referenced.iter().map(|s| s.to_string()).collect();
AliasOptions::parse(args.iter().map(|s| s.to_string()).collect(), &refs)
}
@@ -858,6 +964,20 @@ cmd = [
positional_args: [],
}
"#);
+ // Pathological: multiple `=` in value. `split_once('=')` only splits on
+ // the first, so everything past the first `=` is the value.
+ assert_debug_snapshot!(parse_with(&["deploy", "--foo=a=b=c"], &["foo"]).unwrap(), @r#"
+ AliasOptions {
+ name: "deploy",
+ vars: [
+ (
+ "foo",
+ "a=b=c",
+ ),
+ ],
+ positional_args: [],
+ }
+ "#);
// Empty value accepted on bind.
assert_debug_snapshot!(parse_with(&["deploy", "--env="], &["env"]).unwrap(), @r#"
AliasOptions {
@@ -886,7 +1006,7 @@ cmd = [
#[test]
fn test_parse_space_separated_routing() {
use insta::assert_debug_snapshot;
- // --KEY VALUE binds when KEY is referenced and VALUE is non-flag.
+ // --KEY VALUE binds when KEY is referenced.
assert_debug_snapshot!(parse_with(&["deploy", "--env", "staging"], &["env"]).unwrap(), @r#"
AliasOptions {
name: "deploy",
@@ -910,9 +1030,25 @@ cmd = [
],
}
"#);
- // --KEY followed by another --flag: --KEY forwards alone, the next
- // flag is processed at its normal position.
+ // --KEY --other with KEY referenced: the space form consumes the next
+ // token unconditionally, so `--other` binds as the value of `env`.
+ // Use `--env=VALUE` or reorder flags to avoid this.
assert_debug_snapshot!(parse_with(&["deploy", "--env", "--other"], &["env"]).unwrap(), @r#"
+ AliasOptions {
+ name: "deploy",
+ vars: [
+ (
+ "env",
+ "--other",
+ ),
+ ],
+ positional_args: [],
+ }
+ "#);
+ // Same shape, unreferenced: both consumed as the pair and forwarded.
+ // The next token is not re-examined, so `--other` is not processed
+ // independently.
+ assert_debug_snapshot!(parse_with(&["deploy", "--env", "--other"], &[]).unwrap(), @r#"
AliasOptions {
name: "deploy",
vars: [],
@@ -934,6 +1070,80 @@ cmd = [
"#);
}
+ #[test]
+ fn test_parse_warns_on_footgun_space_form() {
+ // `--KEY VALUE` binds VALUE even when it's flag-shaped. The parser
+ // emits an advisory pointing at `--KEY=VALUE` so the user can
+ // disambiguate if the bind was unintended.
+ let (_, warnings) = parse_with_warnings(&["deploy", "--env", "--other"], &["env"]).unwrap();
+ insta::assert_debug_snapshot!(warnings, @r#"
+ [
+ "`--env --other` bound `env` to `--other` — use `--env=--other` if that was intended",
+ ]
+ "#);
+
+ // Unreferenced pair: both tokens forward as positionals — not a
+ // binding, so no warning.
+ let (_, warnings) = parse_with_warnings(&["deploy", "--env", "--other"], &[]).unwrap();
+ assert!(warnings.is_empty());
+
+ // Ordinary bind: warning stays silent.
+ let (_, warnings) = parse_with_warnings(&["deploy", "--env", "prod"], &["env"]).unwrap();
+ assert!(warnings.is_empty());
+
+ // Hyphenated key: warning shows the user's typed form throughout
+ // (`my-env`), not the canonicalized template name (`my_env`).
+ let (_, warnings) =
+ parse_with_warnings(&["deploy", "--my-env", "--other"], &["my_env"]).unwrap();
+ insta::assert_debug_snapshot!(warnings, @r#"
+ [
+ "`--my-env --other` bound `my-env` to `--other` — use `--my-env=--other` if that was intended",
+ ]
+ "#);
+ }
+
+ #[test]
+ fn test_parse_duplicate_key_last_write_wins() {
+ use insta::assert_debug_snapshot;
+ // Duplicate `--KEY=` bindings are kept in order in the Vec;
+ // `build_hook_context` inserts them into a HashMap so the last one
+ // wins at expansion time. Parser preserves order so that behavior is
+ // testable and deterministic.
+ assert_debug_snapshot!(parse_with(&["deploy", "--env=a", "--env=b"], &["env"]).unwrap(), @r#"
+ AliasOptions {
+ name: "deploy",
+ vars: [
+ (
+ "env",
+ "a",
+ ),
+ (
+ "env",
+ "b",
+ ),
+ ],
+ positional_args: [],
+ }
+ "#);
+ // Mixed space/equals forms follow the same rule.
+ assert_debug_snapshot!(parse_with(&["deploy", "--env", "a", "--env=b"], &["env"]).unwrap(), @r#"
+ AliasOptions {
+ name: "deploy",
+ vars: [
+ (
+ "env",
+ "a",
+ ),
+ (
+ "env",
+ "b",
+ ),
+ ],
+ positional_args: [],
+ }
+ "#);
+ }
+
#[test]
fn test_parse_hyphen_canonicalization() {
use insta::assert_debug_snapshot;
diff --git a/src/commands/config/alias.rs b/src/commands/config/alias.rs
index 4b08721f9..a545bce2a 100644
--- a/src/commands/config/alias.rs
+++ b/src/commands/config/alias.rs
@@ -28,7 +28,7 @@ use worktrunk::config::{
use worktrunk::git::Repository;
use worktrunk::styling::{format_bash_with_gutter, info_message, println};
-use crate::commands::alias::{AliasOptions, AliasSource};
+use crate::commands::alias::{AliasOptions, AliasSource, TOP_LEVEL_BUILTINS};
use crate::commands::command_executor::{
CommandContext, build_hook_context, expand_shell_template,
};
@@ -53,6 +53,8 @@ pub fn handle_alias_show(name: String) -> anyhow::Result<()> {
));
}
+ warn_if_shadowed(&name);
+
for (i, (cfg, source)) in entries.iter().enumerate() {
if i > 0 {
println!();
@@ -63,6 +65,22 @@ pub fn handle_alias_show(name: String) -> anyhow::Result<()> {
Ok(())
}
+/// Emit a warning if `name` is a top-level built-in subcommand. Aliases with
+/// these names are unreachable via `wt <name>` — clap matches the built-in
+/// first. Reported in `show`/`dry-run` so the user finds out at the discovery
+/// surface rather than silently during an invocation that never reaches the
+/// alias.
+fn warn_if_shadowed(name: &str) {
+ if TOP_LEVEL_BUILTINS.contains(&name) {
+ worktrunk::styling::eprintln!(
+ "{}",
+ worktrunk::styling::warning_message(cformat!(
+ "Alias <bold>{name}</> is shadowed by built-in <bold>wt {name}</>"
+ ))
+ );
+ }
+}
+
/// Preview an alias invocation: parse the args, build the template context,
/// and print the rendered command(s) without executing.
///
@@ -96,7 +114,11 @@ pub fn handle_alias_dry_run(name: String, args: Vec<String>) -> anyhow::Result<(
let mut parse_args = Vec::with_capacity(1 + args.len());
parse_args.push(name.clone());
parse_args.extend(args);
- let opts = AliasOptions::parse(parse_args, &referenced)?;
+ let (opts, warnings) = AliasOptions::parse(parse_args, &referenced)?;
+ warn_if_shadowed(&name);
+ for warning in &warnings {
+ worktrunk::styling::eprintln!("{}", worktrunk::styling::warning_message(warning));
+ }
let wt = repo.current_worktree();
let wt_path = wt.root().context("Failed to get worktree root")?;
@@ -114,6 +136,8 @@ pub fn handle_alias_dry_run(name: String, args: Vec<String>) -> anyhow::Result<(
.expect("Vec<String> serialization should never fail"),
);
+ let routing = format_routing_summary(&opts);
+
for (i, (cfg, source)) in entries.iter().enumerate() {
if i > 0 {
println!();
@@ -124,12 +148,48 @@ pub fn handle_alias_dry_run(name: String, args: Vec<String>) -> anyhow::Result<(
.collect::<anyhow::Result<_>>()?;
println!(
"{}",
- format_entry(&name, cfg, *source, &bodies, Some("would run"))
+ format_entry_with_routing(
+ &name,
+ cfg,
+ *source,
+ &bodies,
+ Some("would run"),
+ routing.as_deref()
+ )
);
}
Ok(())
}
+/// Summarize how each CLI token routed, as `# ` comment lines suitable for the
+/// top of a dry-run body. Returns `None` when nothing would have been bound or
+/// forwarded — the common no-args case stays clean.
+fn format_routing_summary(opts: &AliasOptions) -> Option<String> {
+ if opts.vars.is_empty() && opts.positional_args.is_empty() {
+ return None;
+ }
+ let mut lines = String::new();
+ if !opts.vars.is_empty() {
+ let bound = opts
+ .vars
+ .iter()
+ .map(|(k, v)| format!("{k}={}", shell_escape::unix::escape(v.into())))
+ .collect::<Vec<_>>()
+ .join(", ");
+ lines.push_str(&format!("# bound: {bound}\n"));
+ }
+ if !opts.positional_args.is_empty() {
+ let args = opts
+ .positional_args
+ .iter()
+ .map(|a| shell_escape::unix::escape(a.into()).into_owned())
+ .collect::<Vec<_>>()
+ .join(" ");
+ lines.push_str(&format!("# args: {args}\n"));
+ }
+ Some(lines)
+}
+
/// Render a single command template for preview. Mirrors execution-time lazy
/// semantics — see the module-level docstring.
fn render_preview(
@@ -208,6 +268,19 @@ fn format_entry(
source: AliasSource,
bodies: &[String],
verb: Option<&str>,
+) -> String {
+ format_entry_with_routing(name, cfg, source, bodies, verb, None)
+}
+
+/// As `format_entry`, with optional routing comment lines prepended to the
+/// body. Used by `dry-run` to surface `--KEY` bindings and forwarded args.
+fn format_entry_with_routing(
+ name: &str,
+ cfg: &CommandConfig,
+ source: AliasSource,
+ bodies: &[String],
+ verb: Option<&str>,
+ routing: Option<&str>,
) -> String {
let label = source.label();
let suffix = match verb {
@@ -215,8 +288,11 @@ fn format_entry(
None => ":".to_string(),
};
let mut body = String::new();
+ if let Some(routing) = routing {
+ body.push_str(routing);
+ }
for (cmd, rendered) in cfg.commands().zip(bodies) {
- if !body.is_empty() {
+ if !body.is_empty() && !body.ends_with('\n') {
body.push('\n');
}
if let Some(step_name) = &cmd.name {
diff --git a/src/config/expansion.rs b/src/config/expansion.rs
index c86129bff..574262d6c 100644
--- a/src/config/expansion.rs
+++ b/src/config/expansion.rs
@@ -498,25 +498,32 @@ fn setup_template_env(repo: &Repository) -> Environment<'static> {
env
}
-/// Check if a template references a specific top-level variable.
+/// Top-level variables referenced by a single template.
///
/// Uses minijinja's AST analysis rather than string matching, avoiding false
-/// positives from literal text like `template_vars.txt`.
+/// positives from literal text like `template_vars.txt`. Templates that fail
+/// to parse contribute nothing — a syntax error surfaces later at expansion
+/// time with a richer message.
+fn referenced_vars(template: &str) -> std::collections::HashSet<String> {
+ minijinja::Environment::new()
+ .template_from_str(template)
+ .map(|tmpl| tmpl.undeclared_variables(false))
+ .unwrap_or_default()
+}
+
+/// Check if a template references a specific top-level variable.
pub fn template_references_var(template: &str, var: &str) -> bool {
- let env = minijinja::Environment::new();
- let Ok(tmpl) = env.template_from_str(template) else {
- return false;
- };
- tmpl.undeclared_variables(false).contains(var)
+ referenced_vars(template).contains(var)
}
-/// Union of top-level variables referenced by every command in a `CommandConfig`.
+/// Union of top-level variables referenced across every command in `cfg`.
///
/// Drives alias-arg routing in `AliasOptions::parse`: a `--KEY=VALUE` token
/// binds to `{{ KEY }}` only when KEY appears in this set; otherwise it
-/// forwards as a positional. A syntax error in any template fails here so the
-/// user sees it before flags are routed — a silent skip could mask a typo and
-/// silently change how subsequent CLI args bind.
+/// forwards as a positional. A var referenced in any step of a pipeline is
+/// a binding candidate for the whole invocation. A syntax error in any
+/// template fails here so the user sees it before flags are routed — a
+/// silent skip could mask a typo and change how subsequent CLI args bind.
pub fn referenced_vars_for_config(cfg: &super::CommandConfig) -> anyhow::Result<BTreeSet<String>> {
let env = minijinja::Environment::new();
let mut out = BTreeSet::new();
diff --git a/tests/integration_tests/output_system_guard.rs b/tests/integration_tests/output_system_guard.rs
index 59b65d45e..ba9b1442f 100644
--- a/tests/integration_tests/output_system_guard.rs
+++ b/tests/integration_tests/output_system_guard.rs
@@ -38,6 +38,8 @@ const STDOUT_ALLOWED_PATHS: &[&str] = &[
"config/hints.rs",
// Alias introspection output (show / dry-run), intended to be pipeable
"config/alias.rs",
+ // Alias --help hint output (conventional `--help` destination)
+ "alias.rs",
// Template evaluation output for scripting
"eval.rs",
// LLM prompt output for wt step commit --show-prompt
diff --git a/tests/integration_tests/step_alias.rs b/tests/integration_tests/step_alias.rs
index 97a138cc6..f6228ed47 100644
--- a/tests/integration_tests/step_alias.rs
+++ b/tests/integration_tests/step_alias.rs
@@ -1242,6 +1242,79 @@ deploy = "echo hi"
));
}
+/// Retired `--dry-run` bail also fires through `wt step <alias>` — the parser
+/// is shared, but this pins the `step_alias` dispatch route specifically.
+#[rstest]
+fn test_retired_dry_run_flag_via_step(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+deploy = "echo hi"
+"#,
+ );
+ repo.commit("Add alias config");
+ let feature_path = repo.add_worktree("feature");
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["deploy", "--dry-run"],
+ Some(&feature_path),
+ ));
+}
+
+/// `wt <alias> --help` prints guidance rather than forwarding `--help` into
+/// `{{ args }}`. Aliases have no clap-style help page; the canonical
+/// inspection path is `wt config alias show / dry-run`.
+#[rstest]
+fn test_alias_help_flag_prints_hint(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+deploy = "echo hi {{ args }}"
+"#,
+ );
+ repo.commit("Add alias config");
+ let feature_path = repo.add_worktree("feature");
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "deploy",
+ &["--help"],
+ Some(&feature_path),
+ ));
+}
+
+/// `wt <alias> -- --help` bypasses the intercept and forwards `--help` into
+/// the alias body — the documented escape.
+#[rstest]
+fn test_alias_help_flag_after_double_dash_forwards(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+deploy = "echo {{ args }}"
+"#,
+ );
+ repo.commit("Add alias config");
+ let feature_path = repo.add_worktree("feature");
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "deploy",
+ &["--", "--help"],
+ Some(&feature_path),
+ ));
+}
+
/// `wt config alias show <name>` prints the configured template text, source-labeled.
#[rstest]
fn test_config_alias_show_single(mut repo: TestRepo) {
@@ -1395,6 +1468,56 @@ deploy = "echo hi"
));
}
+/// `wt config alias show <name>` on an alias whose name is also a top-level
+/// built-in subcommand warns that the alias is unreachable via `wt <name>`.
+/// The alias is still configured, so the show output itself is shown — the
+/// warning is an advisory on stderr.
+#[rstest]
+fn test_config_alias_show_warns_on_shadowed_name(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+list = "echo custom list"
+"#,
+ );
+ repo.commit("Add alias config");
+ let feature_path = repo.add_worktree("feature");
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "config",
+ &["alias", "show", "list"],
+ Some(&feature_path),
+ ));
+}
+
+/// `wt config alias dry-run` on a shadowed name emits the same advisory as
+/// `show` — both are discovery surfaces, so both point out the shadowing.
+#[rstest]
+fn test_config_alias_dry_run_warns_on_shadowed_name(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+list = "echo custom list"
+"#,
+ );
+ repo.commit("Add alias config");
+ let feature_path = repo.add_worktree("feature");
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "config",
+ &["alias", "dry-run", "list"],
+ Some(&feature_path),
+ ));
+}
+
/// `wt step` with no subcommand lists built-in steps plus configured aliases.
///
/// Skipped on Windows: clap renders `[experimental]` subcommand tags
diff --git a/tests/snapshots/integration__integration_tests__step_alias__alias_help_flag_after_double_dash_forwards.snap b/tests/snapshots/integration__integration_tests__step_alias__alias_help_flag_after_double_dash_forwards.snap
new file mode 100644
index 000000000..fef9bfd3c
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__alias_help_flag_after_double_dash_forwards.snap
@@ -0,0 +1,52 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - deploy
+ - "--"
+ - "--help"
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+▲ origin needs approval to execute 1 command:
+○ alias deploy:
+  echo {{ args }}
+✗ Cannot prompt for approval in non-interactive environment
+↳ To skip prompts in CI/CD, add --yes; to pre-approve commands, run wt config approvals add
diff --git a/tests/snapshots/integration__integration_tests__step_alias__alias_help_flag_prints_hint.snap b/tests/snapshots/integration__integration_tests__step_alias__alias_help_flag_prints_hint.snap
new file mode 100644
index 000000000..f4fe7d27b
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__alias_help_flag_prints_hint.snap
@@ -0,0 +1,50 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - deploy
+ - "--help"
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+`deploy` is an alias. Inspect with:
+ wt config alias show deploy
+ wt config alias dry-run deploy
+Forward `--help` to the alias body with `wt deploy -- --help`.
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__step_alias__config_alias_dry_run_positional_args.snap b/tests/snapshots/integration__integration_tests__step_alias__config_alias_dry_run_positional_args.snap
index 03f52e6c3..02502d65b 100644
--- a/tests/snapshots/integration__integration_tests__step_alias__config_alias_dry_run_positional_args.snap
+++ b/tests/snapshots/integration__integration_tests__step_alias__config_alias_dry_run_positional_args.snap
@@ -47,6 +47,7 @@ success: true
exit_code: 0
----- stdout -----
○ Alias s (project) would run:
+  # args: target-branch
  wt switch target-branch
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__step_alias__config_alias_dry_run_warns_on_shadowed_name.snap b/tests/snapshots/integration__integration_tests__step_alias__config_alias_dry_run_warns_on_shadowed_name.snap
new file mode 100644
index 000000000..106da89e3
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__config_alias_dry_run_warns_on_shadowed_name.snap
@@ -0,0 +1,51 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - config
+ - alias
+ - dry-run
+ - list
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+○ Alias list (project) would run:
+  echo custom list
+
+----- stderr -----
+▲ Alias list is shadowed by built-in wt list
diff --git a/tests/snapshots/integration__integration_tests__step_alias__config_alias_show_warns_on_shadowed_name.snap b/tests/snapshots/integration__integration_tests__step_alias__config_alias_show_warns_on_shadowed_name.snap
new file mode 100644
index 000000000..c7053013f
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__config_alias_show_warns_on_shadowed_name.snap
@@ -0,0 +1,51 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - config
+ - alias
+ - show
+ - list
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+○ Alias list (project):
+  echo custom list
+
+----- stderr -----
+▲ Alias list is shadowed by built-in wt list
diff --git a/tests/snapshots/integration__integration_tests__step_alias__retired_dry_run_flag_via_step.snap b/tests/snapshots/integration__integration_tests__step_alias__retired_dry_run_flag_via_step.snap
new file mode 100644
index 000000000..328f301e3
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__retired_dry_run_flag_via_step.snap
@@ -0,0 +1,48 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - deploy
+ - "--dry-run"
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+✗ --dry-run is no longer supported; use `wt config alias dry-run deploy` instead
diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_referenced_var.snap b/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_referenced_var.snap
index a38698b01..9e3d4b50e 100644
--- a/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_referenced_var.snap
+++ b/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_referenced_var.snap
@@ -47,6 +47,7 @@ success: true
exit_code: 0
----- stdout -----
○ Alias greet (project) would run:
+  # bound: name=World
  echo Hello World from feature
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_space_separated_var.snap b/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_space_separated_var.snap
index 33a4c34fa..90131e6a1 100644
--- a/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_space_separated_var.snap
+++ b/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_space_separated_var.snap
@@ -48,6 +48,7 @@ success: true
exit_code: 0
----- stdout -----
○ Alias greet (project) would run:
+  # bound: name=World
  echo Hello World from feature
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__step_alias__top_level_alias_positional_expands_in_dry_run.snap b/tests/snapshots/integration__integration_tests__step_alias__top_level_alias_positional_expands_in_dry_run.snap
index 03f52e6c3..02502d65b 100644
--- a/tests/snapshots/integration__integration_tests__step_alias__top_level_alias_positional_expands_in_dry_run.snap
+++ b/tests/snapshots/integration__integration_tests__step_alias__top_level_alias_positional_expands_in_dry_run.snap
@@ -47,6 +47,7 @@ success: true
exit_code: 0
----- stdout -----
○ Alias s (project) would run:
+  # args: target-branch
  wt switch target-branch
----- stderr -----