Skip to content

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

feat(step): add alias command for user-defined command templates (#1348)

Maximilian Roos55bc9188b45f
diff --git a/dev/config.example.toml b/dev/config.example.toml
index ce579eae8..e5ff36ba1 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -84,6 +84,16 @@
# # Lower values show the TUI faster; 0 disables timeouts
# # timeout-ms = 200
#
+# ### Aliases
+#
+# Command templates that run with `wt step <name>`. See `wt step` aliases (https://worktrunk.dev/step/#aliases) for usage and flags.
+#
+# [aliases]
+# greet = "echo Hello from {{ branch }}"
+# url = "echo http://localhost:{{ branch | hash_port }}"
+#
+# Aliases defined here apply to all projects. For project-specific aliases, use the project config (https://worktrunk.dev/config/#project-configuration) `[aliases]` section instead.
+#
# ### User project-specific settings
#
# For context:
@@ -96,13 +106,14 @@
#
# #### Setting overrides (Experimental)
#
-# Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run.
+# Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run. Aliases merge — per-project aliases override global aliases on name collision.
#
# [projects."github.com/user/repo"]
# worktree-path = ".worktrees/{{ branch | sanitize }}"
# list.full = true
# merge.squash = false
# post-create.env = "cp .env.example .env"
+# aliases.deploy = "make deploy BRANCH={{ branch }}"
#
# ### Custom prompt templates
#
diff --git a/dev/wt.example.toml b/dev/wt.example.toml
index efb060a72..6be027a9e 100644
--- a/dev/wt.example.toml
+++ b/dev/wt.example.toml
@@ -83,6 +83,16 @@
#
# pre-remove = "docker compose down"
+# ============================================================================
+# Aliases (experimental) — run with `wt step <name>`
+# ============================================================================
+# Command templates that support the same variables as hooks.
+# Project-config aliases require command approval on first run.
+#
+# [aliases]
+# deploy = "make deploy BRANCH={{ branch }}"
+# url = "echo http://localhost:{{ branch | hash_port }}"
+
# ============================================================================
# Dev Server URL (shown in `wt list`)
# ============================================================================
diff --git a/docs/content/config.md b/docs/content/config.md
index fa75e9af2..66cee8c05 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -164,6 +164,18 @@ Configuration for `wt switch` interactive picker.
# timeout-ms = 200
```
+### Aliases
+
+Command templates that run with `wt step <name>`. See [`wt step` aliases](@/step.md#aliases) for usage and flags.
+
+```toml
+[aliases]
+greet = "echo Hello from {{ branch }}"
+url = "echo http://localhost:{{ branch | hash_port }}"
+```
+
+Aliases defined here apply to all projects. For project-specific aliases, use the [project config](@/config.md#project-configuration) `[aliases]` section instead.
+
### User project-specific settings
For context:
@@ -176,7 +188,7 @@ Entries are keyed by project identifier (e.g., `github.com/user/repo`).
#### Setting overrides (Experimental)
-Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run.
+Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run. Aliases merge — per-project aliases override global aliases on name collision.
```toml
[projects."github.com/user/repo"]
@@ -184,6 +196,7 @@ worktree-path = ".worktrees/{{ branch | sanitize }}"
list.full = true
merge.squash = false
post-create.env = "cp .env.example .env"
+aliases.deploy = "make deploy BRANCH={{ branch }}"
```
### Custom prompt templates
@@ -299,6 +312,11 @@ url = "http://localhost:{{ branch | hash_port }}"
# Override CI platform detection for self-hosted instances
[ci]
platform = "github" # or "gitlab"
+
+# Command aliases (run with wt step <name>)
+[aliases]
+deploy = "make deploy BRANCH={{ branch }}"
+test = "cargo test"
```
# Shell Integration
diff --git a/docs/content/step.md b/docs/content/step.md
index cd09ce116..c533ad58f 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -40,6 +40,29 @@ wt step push
- `promote` — [experimental] Put a branch into the main worktree
- `prune` — Remove worktrees and branches merged into the default branch
- `relocate` — [experimental] Move worktrees to expected paths
+- `<alias>` — [experimental] Run a configured command alias
+
+## Aliases
+
+Custom command templates configured in user config (`~/.config/worktrunk/config.toml`) or project config (`.config/wt.toml`). Aliases support the same [template variables](@/hook.md#template-variables) as hooks.
+
+```toml
+# .config/wt.toml
+[aliases]
+deploy = "make deploy BRANCH={{ branch }}"
+port = "echo http://localhost:{{ branch | hash_port }}"
+```
+
+```bash
+wt step deploy # run the alias
+wt step deploy --dry-run # show expanded command
+wt step deploy --var env=staging # pass extra template variables
+wt step deploy --yes # skip approval prompt
+```
+
+When defined in both user and project config, user aliases take precedence. Project-config aliases require [command approval](@/hook.md#command-approval) on first run (same as project hooks). User-config aliases are trusted.
+
+Alias names that match a built-in step command (`commit`, `squash`, etc.) are shadowed by the built-in and will never run.
## See also
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index 0cacadec1..8a6204bb1 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -155,6 +155,18 @@ Configuration for `wt switch` interactive picker.
# timeout-ms = 200
```
+### Aliases
+
+Command templates that run with `wt step <name>`. See [`wt step` aliases](https://worktrunk.dev/step/#aliases) for usage and flags.
+
+```toml
+[aliases]
+greet = "echo Hello from {{ branch }}"
+url = "echo http://localhost:{{ branch | hash_port }}"
+```
+
+Aliases defined here apply to all projects. For project-specific aliases, use the [project config](https://worktrunk.dev/config/#project-configuration) `[aliases]` section instead.
+
### User project-specific settings
For context:
@@ -167,7 +179,7 @@ Entries are keyed by project identifier (e.g., `github.com/user/repo`).
#### Setting overrides (Experimental)
-Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run.
+Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run. Aliases merge — per-project aliases override global aliases on name collision.
```toml
[projects."github.com/user/repo"]
@@ -175,6 +187,7 @@ worktree-path = ".worktrees/{{ branch | sanitize }}"
list.full = true
merge.squash = false
post-create.env = "cp .env.example .env"
+aliases.deploy = "make deploy BRANCH={{ branch }}"
```
### Custom prompt templates
@@ -290,6 +303,11 @@ url = "http://localhost:{{ branch | hash_port }}"
# Override CI platform detection for self-hosted instances
[ci]
platform = "github" # or "gitlab"
+
+# Command aliases (run with wt step <name>)
+[aliases]
+deploy = "make deploy BRANCH={{ branch }}"
+test = "cargo test"
```
# Shell Integration
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 34d068247..b8bbfadb0 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -31,6 +31,29 @@ wt step push
- `promote` — [experimental] Put a branch into the main worktree
- `prune` — Remove worktrees and branches merged into the default branch
- `relocate` — [experimental] Move worktrees to expected paths
+- `<alias>` — [experimental] Run a configured command alias
+
+## Aliases
+
+Custom command templates configured in user config (`~/.config/worktrunk/config.toml`) or project config (`.config/wt.toml`). Aliases support the same [template variables](https://worktrunk.dev/hook/#template-variables) as hooks.
+
+```toml
+# .config/wt.toml
+[aliases]
+deploy = "make deploy BRANCH={{ branch }}"
+port = "echo http://localhost:{{ branch | hash_port }}"
+```
+
+```bash
+wt step deploy # run the alias
+wt step deploy --dry-run # show expanded command
+wt step deploy --var env=staging # pass extra template variables
+wt step deploy --yes # skip approval prompt
+```
+
+When defined in both user and project config, user aliases take precedence. Project-config aliases require [command approval](https://worktrunk.dev/hook/#command-approval) on first run (same as project hooks). User-config aliases are trusted.
+
+Alias names that match a built-in step command (`commit`, `squash`, etc.) are shadowed by the built-in and will never run.
## Command reference
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index fc7d3b1b0..46c88832f 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1032,6 +1032,29 @@ wt step push
- `promote` — [experimental] Put a branch into the main worktree
- `prune` — Remove worktrees and branches merged into the default branch
- `relocate` — [experimental] Move worktrees to expected paths
+- `<alias>` — [experimental] Run a configured command alias
+
+## Aliases
+
+Custom command templates configured in user config (`~/.config/worktrunk/config.toml`) or project config (`.config/wt.toml`). Aliases support the same [template variables](@/hook.md#template-variables) as hooks.
+
+```toml
+# .config/wt.toml
+[aliases]
+deploy = "make deploy BRANCH={{ branch }}"
+port = "echo http://localhost:{{ branch | hash_port }}"
+```
+
+```console
+wt step deploy # run the alias
+wt step deploy --dry-run # show expanded command
+wt step deploy --var env=staging # pass extra template variables
+wt step deploy --yes # skip approval prompt
+```
+
+When defined in both user and project config, user aliases take precedence. Project-config aliases require [command approval](@/hook.md#command-approval) on first run (same as project hooks). User-config aliases are trusted.
+
+Alias names that match a built-in step command (`commit`, `squash`, etc.) are shadowed by the built-in and will never run.
## See also
@@ -1639,6 +1662,18 @@ Configuration for `wt switch` interactive picker.
# timeout-ms = 200
```
+### Aliases
+
+Command templates that run with `wt step <name>`. See [`wt step` aliases](@/step.md#aliases) for usage and flags.
+
+```toml
+[aliases]
+greet = "echo Hello from {{ branch }}"
+url = "echo http://localhost:{{ branch | hash_port }}"
+```
+
+Aliases defined here apply to all projects. For project-specific aliases, use the [project config](@/config.md#project-configuration) `[aliases]` section instead.
+
### User project-specific settings
For context:
@@ -1651,7 +1686,7 @@ Entries are keyed by project identifier (e.g., `github.com/user/repo`).
#### Setting overrides (Experimental)
-Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run.
+Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run. Aliases merge — per-project aliases override global aliases on name collision.
```toml
[projects."github.com/user/repo"]
@@ -1659,6 +1694,7 @@ worktree-path = ".worktrees/{{ branch | sanitize }}"
list.full = true
merge.squash = false
post-create.env = "cp .env.example .env"
+aliases.deploy = "make deploy BRANCH={{ branch }}"
```
### Custom prompt templates
@@ -1774,6 +1810,11 @@ url = "http://localhost:{{ branch | hash_port }}"
# Override CI platform detection for self-hosted instances
[ci]
platform = "github" # or "gitlab"
+
+# Command aliases (run with wt step <name>)
+[aliases]
+deploy = "make deploy BRANCH={{ branch }}"
+test = "cargo test"
```
# Shell Integration
diff --git a/src/cli/step.rs b/src/cli/step.rs
index f091640e1..ecfc562fd 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -2,6 +2,7 @@ use clap::Subcommand;
/// Run individual operations
#[derive(Subcommand)]
+#[command(allow_external_subcommands = true)]
pub enum StepCommand {
/// Stage and commit with LLM-generated message
#[command(
@@ -551,4 +552,8 @@ Note: This command is experimental and may change in future versions.
#[arg(long)]
clobber: bool,
},
+
+ /// Catch-all for alias lookup
+ #[command(external_subcommand)]
+ External(Vec<String>),
}
diff --git a/src/commands/alias.rs b/src/commands/alias.rs
new file mode 100644
index 000000000..060cdda2c
--- /dev/null
+++ b/src/commands/alias.rs
@@ -0,0 +1,378 @@
+//! Alias command implementation
+//!
+//! Runs user-defined command aliases configured in `[aliases]` sections
+//! of user config or project config. Aliases are command templates that
+//! support the same template variables as hooks.
+//!
+//! Project-config aliases require command approval (same as project hooks).
+//! User-config aliases are trusted and skip approval. When an alias exists
+//! in both configs, the user version wins and is trusted.
+
+use std::collections::{BTreeMap, HashMap};
+
+use anyhow::{Context, bail};
+use color_print::cformat;
+use worktrunk::config::{ProjectConfig, UserConfig, expand_template};
+use worktrunk::git::{Repository, WorktrunkError};
+use worktrunk::styling::{eprintln, format_with_gutter, info_message, progress_message};
+
+use crate::commands::command_approval::approve_alias;
+use crate::commands::command_executor::{CommandContext, build_hook_context};
+use crate::commands::for_each::{CommandError, run_command_streaming};
+
+/// Built-in `wt step` subcommand names. Aliases with these names are
+/// shadowed by the built-in and will never run.
+const BUILTIN_STEP_COMMANDS: &[&str] = &[
+ "commit",
+ "copy-ignored",
+ "diff",
+ "for-each",
+ "promote",
+ "prune",
+ "push",
+ "rebase",
+ "relocate",
+ "squash",
+];
+
+/// Options parsed from the external subcommand args.
+#[derive(Debug)]
+pub struct AliasOptions {
+ pub name: String,
+ pub dry_run: bool,
+ pub yes: bool,
+ pub vars: Vec<(String, String)>,
+}
+
+impl AliasOptions {
+ /// Parse alias options from the external subcommand args.
+ ///
+ /// First element is the alias name, remaining are flags:
+ /// `--dry-run`, `--yes`/`-y`, and `--var KEY=VALUE`.
+ pub fn parse(args: Vec<String>) -> anyhow::Result<Self> {
+ let Some(name) = args.first().cloned() else {
+ bail!("Missing alias name");
+ };
+
+ let mut dry_run = false;
+ let mut yes = false;
+ let mut vars = Vec::new();
+ let mut i = 1;
+ while i < args.len() {
+ match args[i].as_str() {
+ "--dry-run" => dry_run = true,
+ "--yes" | "-y" => yes = true,
+ "--var" => {
+ i += 1;
+ if i >= args.len() {
+ bail!("--var requires a KEY=VALUE argument");
+ }
+ let pair = parse_var(&args[i])?;
+ vars.push(pair);
+ }
+ arg if arg.starts_with("--var=") => {
+ let pair = parse_var(arg.strip_prefix("--var=").unwrap())?;
+ vars.push(pair);
+ }
+ other => {
+ bail!("Unexpected argument '{other}' for alias '{name}'");
+ }
+ }
+ i += 1;
+ }
+
+ Ok(Self {
+ name,
+ dry_run,
+ yes,
+ vars,
+ })
+ }
+}
+
+fn parse_var(s: &str) -> anyhow::Result<(String, String)> {
+ let (key, value) = s.split_once('=').context("--var value must be KEY=VALUE")?;
+ if key.is_empty() {
+ bail!("--var key must not be empty (got '={value}')");
+ }
+ Ok((key.to_string(), value.to_string()))
+}
+
+/// Determine whether an alias requires project-config approval.
+///
+/// An alias needs approval when:
+/// - It exists in project config AND
+/// - It does NOT exist in user config (user overrides are trusted)
+fn alias_needs_approval(
+ alias_name: &str,
+ project_config: &Option<ProjectConfig>,
+ user_config: &UserConfig,
+ project_id: Option<&str>,
+) -> Option<String> {
+ // Check if alias exists in project config
+ let project_template = project_config
+ .as_ref()
+ .and_then(|pc| pc.aliases.as_ref())
+ .and_then(|a| a.get(alias_name));
+
+ let project_template = project_template?;
+
+ // Check if user config overrides this alias (user overrides are trusted)
+ let user_aliases = user_config.aliases(project_id);
+ if user_aliases.contains_key(alias_name) {
+ return None;
+ }
+
+ Some(project_template.clone())
+}
+
+/// Run a configured alias by name.
+///
+/// Looks up the alias in merged config (project config + user config),
+/// expands the template, and executes it. Project-config aliases require
+/// command approval before execution.
+pub fn step_alias(opts: AliasOptions) -> anyhow::Result<()> {
+ let repo = Repository::current()?;
+ let user_config = UserConfig::load()?;
+ let project_id = repo.project_identifier().ok();
+ let project_config = ProjectConfig::load(&repo, true)?;
+
+ // Merge aliases: project config first, then user config overrides
+ let mut aliases: BTreeMap<String, String> = project_config
+ .as_ref()
+ .and_then(|pc| pc.aliases.clone())
+ .unwrap_or_default();
+ aliases.extend(user_config.aliases(project_id.as_deref()));
+
+ let Some(template) = aliases.get(&opts.name) else {
+ // Filter out aliases that shadow built-in step commands — they're
+ // unreachable since clap dispatches to the built-in first.
+ let available: Vec<_> = aliases
+ .keys()
+ .filter(|k| !BUILTIN_STEP_COMMANDS.contains(&k.as_str()))
+ .map(|k| k.as_str())
+ .collect();
+ if available.is_empty() {
+ bail!(
+ "Unknown step command '{}' (no aliases configured)",
+ opts.name,
+ );
+ } else {
+ bail!(
+ "Unknown alias '{}' (available: {})",
+ opts.name,
+ available.join(", "),
+ );
+ }
+ };
+
+ // Check if this alias needs project-config approval (skip for --dry-run)
+ if !opts.dry_run
+ && let Some(project_template) = alias_needs_approval(
+ &opts.name,
+ &project_config,
+ &user_config,
+ project_id.as_deref(),
+ )
+ {
+ let project_id = project_id
+ .as_deref()
+ .context("Cannot determine project identifier for alias approval")?;
+ let approved = approve_alias(&project_template, &opts.name, project_id, opts.yes)?;
+ if !approved {
+ return Ok(());
+ }
+ }
+
+ // Build hook context for template expansion
+ let wt = repo.current_worktree();
+ let wt_path = wt.root().context("Failed to get worktree root")?;
+ let branch = wt.branch().ok().flatten();
+ let ctx = CommandContext::new(&repo, &user_config, branch.as_deref(), &wt_path, false);
+
+ let extra_refs: Vec<(&str, &str)> = opts
+ .vars
+ .iter()
+ .map(|(k, v)| (k.as_str(), v.as_str()))
+ .collect();
+ let context_map = build_hook_context(&ctx, &extra_refs)?;
+
+ // Convert to &str references for expand_template
+ let vars: HashMap<&str, &str> = context_map
+ .iter()
+ .map(|(k, v)| (k.as_str(), v.as_str()))
+ .collect();
+
+ let command = expand_template(template, &vars, true, &repo, &opts.name)?;
+
+ if opts.dry_run {
+ eprintln!(
+ "{}",
+ info_message(cformat!(
+ "Alias <bold>{}</> would run:\n{}",
+ opts.name,
+ format_with_gutter(&command, None)
+ ))
+ );
+ return Ok(());
+ }
+
+ eprintln!(
+ "{}",
+ progress_message(cformat!("Running alias <bold>{}</>", opts.name))
+ );
+
+ // Build JSON context for stdin
+ let context_json = serde_json::to_string(&context_map)
+ .expect("HashMap<String, String> serialization should never fail");
+
+ match run_command_streaming(&command, &wt_path, Some(&context_json)) {
+ Ok(()) => Ok(()),
+ Err(CommandError::SpawnFailed(err)) => {
+ bail!("Failed to run alias '{}': {}", opts.name, err);
+ }
+ Err(CommandError::ExitCode(exit_code)) => Err(WorktrunkError::AlreadyDisplayed {
+ exit_code: exit_code.unwrap_or(1),
+ }
+ .into()),
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn parse(args: &[&str]) -> anyhow::Result<AliasOptions> {
+ AliasOptions::parse(args.iter().map(|s| s.to_string()).collect())
+ }
+
+ #[test]
+ fn test_parse_name_only() {
+ let opts = parse(&["deploy"]).unwrap();
+ assert_eq!(opts.name, "deploy");
+ assert!(!opts.dry_run);
+ assert!(!opts.yes);
+ assert!(opts.vars.is_empty());
+ }
+
+ #[test]
+ fn test_parse_dry_run() {
+ let opts = parse(&["deploy", "--dry-run"]).unwrap();
+ assert!(opts.dry_run);
+ }
+
+ #[test]
+ fn test_parse_yes_long() {
+ let opts = parse(&["deploy", "--yes"]).unwrap();
+ assert!(opts.yes);
+ }
+
+ #[test]
+ fn test_parse_yes_short() {
+ let opts = parse(&["deploy", "-y"]).unwrap();
+ assert!(opts.yes);
+ }
+
+ #[test]
+ fn test_parse_var_separate() {
+ let opts = parse(&["deploy", "--var", "key=value"]).unwrap();
+ assert_eq!(opts.vars, vec![("key".into(), "value".into())]);
+ }
+
+ #[test]
+ fn test_parse_var_equals() {
+ let opts = parse(&["deploy", "--var=key=value"]).unwrap();
+ assert_eq!(opts.vars, vec![("key".into(), "value".into())]);
+ }
+
+ #[test]
+ fn test_parse_var_value_with_equals() {
+ let opts = parse(&["deploy", "--var", "url=http://host?a=1"]).unwrap();
+ assert_eq!(opts.vars[0], ("url".into(), "http://host?a=1".into()));
+ }
+
+ #[test]
+ fn test_parse_multiple_vars() {
+ let opts = parse(&["deploy", "--var", "a=1", "--var", "b=2", "--dry-run"]).unwrap();
+ assert_eq!(opts.vars.len(), 2);
+ assert!(opts.dry_run);
+ }
+
+ #[test]
+ fn test_parse_missing_name() {
+ let err = parse(&[]).unwrap_err();
+ assert!(err.to_string().contains("Missing alias name"));
+ }
+
+ #[test]
+ fn test_parse_var_missing_value() {
+ let err = parse(&["deploy", "--var"]).unwrap_err();
+ assert!(err.to_string().contains("--var requires a KEY=VALUE"));
+ }
+
+ #[test]
+ fn test_parse_var_no_equals() {
+ let err = parse(&["deploy", "--var", "noequals"]).unwrap_err();
+ assert!(err.to_string().contains("KEY=VALUE"));
+ }
+
+ #[test]
+ fn test_parse_unknown_flag() {
+ let err = parse(&["deploy", "--verbose"]).unwrap_err();
+ assert!(err.to_string().contains("Unexpected argument '--verbose'"));
+ }
+
+ #[test]
+ fn test_parse_positional_arg_rejected() {
+ let err = parse(&["deploy", "arg1"]).unwrap_err();
+ assert!(err.to_string().contains("Unexpected argument 'arg1'"));
+ }
+
+ #[test]
+ fn test_parse_var_empty_key_rejected() {
+ let err = parse(&["deploy", "--var", "=value"]).unwrap_err();
+ assert!(err.to_string().contains("--var key must not be empty"));
+ }
+
+ #[test]
+ fn test_parse_var_empty_value_accepted() {
+ let opts = parse(&["deploy", "--var", "key="]).unwrap();
+ assert_eq!(opts.vars, vec![("key".into(), String::new())]);
+ }
+
+ /// Verify BUILTIN_STEP_COMMANDS stays in sync with the actual StepCommand variants.
+ ///
+ /// If a new step subcommand is added without updating BUILTIN_STEP_COMMANDS,
+ /// this test fails — preventing aliases from silently conflicting with built-ins.
+ #[test]
+ fn test_builtin_step_commands_matches_clap() {
+ use crate::cli::Cli;
+ use clap::CommandFactory;
+
+ let app = Cli::command();
+ let step_cmd = app
+ .get_subcommands()
+ .find(|c| c.get_name() == "step")
+ .expect("step subcommand exists");
+
+ let clap_names: Vec<&str> = step_cmd.get_subcommands().map(|s| s.get_name()).collect();
+
+ // Every clap subcommand should be in BUILTIN_STEP_COMMANDS
+ for name in &clap_names {
+ assert!(
+ BUILTIN_STEP_COMMANDS.contains(name),
+ "Step subcommand '{name}' is missing from BUILTIN_STEP_COMMANDS. \
+ Add it to prevent aliases from silently conflicting with the built-in."
+ );
+ }
+
+ // Every BUILTIN_STEP_COMMANDS entry should still be a real subcommand
+ for name in BUILTIN_STEP_COMMANDS {
+ assert!(
+ clap_names.contains(name),
+ "BUILTIN_STEP_COMMANDS contains '{name}' but no such step subcommand exists. \
+ Remove it from the list."
+ );
+ }
+ }
+}
diff --git a/src/commands/command_approval.rs b/src/commands/command_approval.rs
index 8313f421e..042f208b1 100644
--- a/src/commands/command_approval.rs
+++ b/src/commands/command_approval.rs
@@ -30,7 +30,7 @@ use worktrunk::styling::{
};
use super::hook_filter::{HookSource, ParsedFilter};
-use super::project_config::{HookCommand, collect_commands_for_hooks};
+use super::project_config::{ApprovableCommand, Phase, collect_commands_for_hooks};
/// Batch approval helper used when multiple commands are queued for execution.
/// Returns `Ok(true)` when execution may continue, `Ok(false)` when the user
@@ -42,13 +42,13 @@ use super::project_config::{HookCommand, collect_commands_for_hooks};
/// # Parameters
/// - `commands_already_filtered`: If true, commands list is pre-filtered; skip filtering by approval status
pub fn approve_command_batch(
- commands: &[HookCommand],
+ commands: &[ApprovableCommand],
project_id: &str,
approvals: &Approvals,
yes: bool,
commands_already_filtered: bool,
) -> anyhow::Result<bool> {
- let needs_approval: Vec<&HookCommand> = commands
+ let needs_approval: Vec<&ApprovableCommand> = commands
.iter()
.filter(|cmd| {
commands_already_filtered
@@ -92,7 +92,10 @@ pub fn approve_command_batch(
Ok(true)
}
-fn prompt_for_batch_approval(commands: &[&HookCommand], project_id: &str) -> anyhow::Result<bool> {
+fn prompt_for_batch_approval(
+ commands: &[&ApprovableCommand],
+ project_id: &str,
+) -> anyhow::Result<bool> {
// Extract just the directory name for display
let project_name = Path::new(project_id)
.file_name()
@@ -110,9 +113,8 @@ fn prompt_for_batch_approval(commands: &[&HookCommand], project_id: &str) -> any
for cmd in commands {
// Format as: {phase} {bold}{name}{bold:#}:
- // Phase comes from the hook type (e.g., "pre-commit", "pre-merge")
// Uses INFO_SYMBOL (○) since this is a preview, not active execution
- let phase = cmd.hook_type.to_string();
+ let phase = cmd.phase.to_string();
let label = match &cmd.command.name {
Some(name) => cformat!("{INFO_SYMBOL} {phase} <bold>{name}</>:"),
None => format!("{INFO_SYMBOL} {phase}:"),
@@ -144,6 +146,28 @@ fn prompt_for_batch_approval(commands: &[&HookCommand], project_id: &str) -> any
Ok(response.trim().eq_ignore_ascii_case("y"))
}
+/// Approve a project-config alias before execution.
+///
+/// Returns `Ok(true)` if approved (or already approved), `Ok(false)` if declined.
+pub fn approve_alias(
+ template: &str,
+ alias_name: &str,
+ project_id: &str,
+ yes: bool,
+) -> anyhow::Result<bool> {
+ let approvals = Approvals::load().context("Failed to load approvals")?;
+
+ let cmd = ApprovableCommand {
+ phase: Phase::Alias,
+ command: worktrunk::config::Command::new(
+ Some(alias_name.to_string()),
+ template.to_string(),
+ ),
+ };
+
+ approve_command_batch(&[cmd], project_id, &approvals, yes, false)
+}
+
/// Collect project commands for hooks and request batch approval.
///
/// This is the "gate" function that should be called at command entry points
diff --git a/src/commands/for_each.rs b/src/commands/for_each.rs
index f15e72ba4..3c58fbd3a 100644
--- a/src/commands/for_each.rs
+++ b/src/commands/for_each.rs
@@ -138,7 +138,7 @@ pub fn step_for_each(args: Vec<String>) -> anyhow::Result<()> {
}
/// Error from running a command in a worktree
-enum CommandError {
+pub(crate) enum CommandError {
/// Command failed to spawn (e.g., command not found, permission denied)
SpawnFailed(String),
/// Command exited with non-zero status
@@ -159,7 +159,7 @@ enum CommandError {
/// - Tee stderr (stream + capture) for gutter display on failure
/// - Add `--gutter` flag to capture and format output
/// - Accept current behavior as consistent with hooks
-fn run_command_streaming(
+pub(crate) fn run_command_streaming(
command: &str,
working_dir: &std::path::Path,
stdin_content: Option<&str>,
diff --git a/src/commands/merge.rs b/src/commands/merge.rs
index 0fdd90552..ed14a1e9c 100644
--- a/src/commands/merge.rs
+++ b/src/commands/merge.rs
@@ -9,7 +9,7 @@ use super::command_executor::CommandContext;
use super::commit::CommitOptions;
use super::context::CommandEnv;
use super::hooks::{HookFailureStrategy, execute_hook};
-use super::project_config::{HookCommand, collect_commands_for_hooks};
+use super::project_config::{ApprovableCommand, collect_commands_for_hooks};
use super::repository_ext::RepositoryCliExt;
use super::worktree::{
BranchDeletionMode, MergeOperations, RemoveResult, get_path_mismatch, handle_push,
@@ -45,7 +45,7 @@ fn collect_merge_commands(
verify: bool,
will_remove: bool,
squash_enabled: bool,
-) -> anyhow::Result<(Vec<HookCommand>, String)> {
+) -> anyhow::Result<(Vec<ApprovableCommand>, String)> {
let mut all_commands = Vec::new();
let project_config = match repo.load_project_config()? {
Some(cfg) => cfg,
diff --git a/src/commands/mod.rs b/src/commands/mod.rs
index ac8be8637..e4d9db7a6 100644
--- a/src/commands/mod.rs
+++ b/src/commands/mod.rs
@@ -1,3 +1,4 @@
+mod alias;
pub(crate) mod branch_deletion;
pub(crate) mod command_approval;
pub(crate) mod command_executor;
@@ -23,6 +24,7 @@ pub(crate) mod statusline;
pub(crate) mod step_commands;
pub(crate) mod worktree;
+pub(crate) use alias::{AliasOptions, step_alias};
pub(crate) use config::{
handle_config_create, handle_config_show, handle_config_update, handle_hints_clear,
handle_hints_get, handle_logs_get, handle_state_clear, handle_state_clear_all,
diff --git a/src/commands/project_config.rs b/src/commands/project_config.rs
index 4c122d7b5..e5dff840e 100644
--- a/src/commands/project_config.rs
+++ b/src/commands/project_config.rs
@@ -1,9 +1,28 @@
+use std::fmt;
+
use worktrunk::config::{Command, ProjectConfig};
use worktrunk::git::HookType;
+/// What triggered a project command — determines the label in approval prompts.
+#[derive(Clone)]
+pub enum Phase {
+ Hook(HookType),
+ Alias,
+}
+
+impl fmt::Display for Phase {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ match self {
+ Phase::Hook(hook_type) => write!(f, "{hook_type}"),
+ Phase::Alias => write!(f, "alias"),
+ }
+ }
+}
+
+/// A project-config command pending approval.
#[derive(Clone)]
-pub struct HookCommand {
- pub hook_type: HookType,
+pub struct ApprovableCommand {
+ pub phase: Phase,
pub command: Command,
}
@@ -11,7 +30,7 @@ pub struct HookCommand {
pub fn collect_commands_for_hooks(
project_config: &ProjectConfig,
hooks: &[HookType],
-) -> Vec<HookCommand> {
+) -> Vec<ApprovableCommand> {
let mut commands = Vec::new();
for hook in hooks {
if let Some(config) = project_config.hooks.get(*hook) {
@@ -20,8 +39,8 @@ pub fn collect_commands_for_hooks(
.commands()
.iter()
.cloned()
- .map(|command| HookCommand {
- hook_type: *hook,
+ .map(|command| ApprovableCommand {
+ phase: Phase::Hook(*hook),
command,
}),
);
@@ -117,6 +136,9 @@ build = "npm run build"
let config = make_project_config_with_hooks();
let commands = collect_commands_for_hooks(&config, &[HookType::PostCreate]);
assert_eq!(commands.len(), 1);
- assert_eq!(commands[0].hook_type, HookType::PostCreate);
+ assert!(matches!(
+ commands[0].phase,
+ Phase::Hook(HookType::PostCreate)
+ ));
}
}
diff --git a/src/config/project.rs b/src/config/project.rs
index 4d47c8b0e..9b797ec09 100644
--- a/src/config/project.rs
+++ b/src/config/project.rs
@@ -2,6 +2,8 @@
//!
//! Configuration that is checked into the repository and shared across all developers.
+use std::collections::BTreeMap;
+
use config::ConfigError;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
@@ -108,6 +110,19 @@ pub struct ProjectConfig {
/// CI configuration (platform override)
#[serde(default)]
pub ci: Option<ProjectCiConfig>,
+
+ /// \[experimental\] Command aliases for `wt step <name>`.
+ ///
+ /// Each alias maps a name to a command template. All hook template variables
+ /// are available (e.g., `{{ branch }}`, `{{ worktree_path }}`).
+ ///
+ /// ```toml
+ /// [aliases]
+ /// deploy = "cd {{ worktree_path }} && make deploy"
+ /// lint = "npm run lint"
+ /// ```
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub aliases: Option<BTreeMap<String, String>>,
}
impl ProjectConfig {
diff --git a/src/config/user/accessors.rs b/src/config/user/accessors.rs
index 1e586b4ac..99e71cc7c 100644
--- a/src/config/user/accessors.rs
+++ b/src/config/user/accessors.rs
@@ -3,7 +3,7 @@
//! These methods on `UserConfig` return the effective configuration for a given
//! project by merging global settings with project-specific overrides.
-use std::collections::HashMap;
+use std::collections::{BTreeMap, HashMap};
use crate::config::HooksConfig;
use crate::config::expansion::expand_template;
@@ -184,6 +184,20 @@ impl UserConfig {
}
}
+ /// Returns effective aliases for a specific project.
+ ///
+ /// Merges global user aliases with per-project user aliases (per-project overrides on collision).
+ pub fn aliases(&self, project: Option<&str>) -> BTreeMap<String, String> {
+ let mut result = self.configs.aliases.clone().unwrap_or_default();
+ if let Some(proj_aliases) = project
+ .and_then(|p| self.projects.get(p))
+ .and_then(|proj| proj.overrides.aliases.as_ref())
+ {
+ result.extend(proj_aliases.iter().map(|(k, v)| (k.clone(), v.clone())));
+ }
+ result
+ }
+
// ---- Resolved config (concrete types with defaults applied) ----
/// Returns all resolved config with defaults applied.
diff --git a/src/config/user/sections.rs b/src/config/user/sections.rs
index 29e6dfd24..e284c3cab 100644
--- a/src/config/user/sections.rs
+++ b/src/config/user/sections.rs
@@ -3,6 +3,8 @@
//! These structs represent individual configuration sections that can be set
//! globally or per-project. Each implements the `Merge` trait for layering.
+use std::collections::BTreeMap;
+
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
@@ -427,6 +429,19 @@ pub struct OverridableConfig {
/// **DEPRECATED**: Use `[switch.picker]` instead.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub select: Option<SelectConfig>,
+
+ /// \[experimental\] Command aliases for `wt step <name>`.
+ ///
+ /// Each alias maps a name to a command template. All hook template variables
+ /// are available (e.g., `{{ branch }}`, `{{ worktree_path }}`).
+ ///
+ /// ```toml
+ /// [aliases]
+ /// deploy = "cd {{ worktree_path }} && make deploy"
+ /// lint = "npm run lint"
+ /// ```
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub aliases: Option<BTreeMap<String, String>>,
}
impl OverridableConfig {
@@ -441,6 +456,7 @@ impl OverridableConfig {
&& self.merge.is_none()
&& self.switch.is_none()
&& self.select.is_none()
+ && self.aliases.is_none()
}
}
@@ -459,6 +475,24 @@ impl Merge for OverridableConfig {
merge: merge_optional(self.merge.as_ref(), other.merge.as_ref()),
switch: merge_optional(self.switch.as_ref(), other.switch.as_ref()),
select: merge_optional(self.select.as_ref(), other.select.as_ref()),
+ aliases: merge_alias_maps(&self.aliases, &other.aliases),
+ }
+ }
+}
+
+/// Merge two optional alias maps. Other's entries override base on collision.
+fn merge_alias_maps(
+ base: &Option<BTreeMap<String, String>>,
+ other: &Option<BTreeMap<String, String>>,
+) -> Option<BTreeMap<String, String>> {
+ match (base, other) {
+ (None, None) => None,
+ (Some(b), None) => Some(b.clone()),
+ (None, Some(o)) => Some(o.clone()),
+ (Some(b), Some(o)) => {
+ let mut merged = b.clone();
+ merged.extend(o.iter().map(|(k, v)| (k.clone(), v.clone())));
+ Some(merged)
}
}
}
@@ -518,3 +552,37 @@ impl UserProjectOverrides {
self.commit_generation.is_none() && self.overrides.is_empty()
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn test_merge_alias_maps_both_none() {
+ assert_eq!(merge_alias_maps(&None, &None), None);
+ }
+
+ #[test]
+ fn test_merge_alias_maps_base_only() {
+ let base = BTreeMap::from([("a".into(), "1".into())]);
+ let result = merge_alias_maps(&Some(base.clone()), &None);
+ assert_eq!(result, Some(base));
+ }
+
+ #[test]
+ fn test_merge_alias_maps_other_only() {
+ let other = BTreeMap::from([("b".into(), "2".into())]);
+ let result = merge_alias_maps(&None, &Some(other.clone()));
+ assert_eq!(result, Some(other));
+ }
+
+ #[test]
+ fn test_merge_alias_maps_other_overrides_base() {
+ let base = BTreeMap::from([("a".into(), "1".into()), ("shared".into(), "base".into())]);
+ let other = BTreeMap::from([("b".into(), "2".into()), ("shared".into(), "other".into())]);
+ let result = merge_alias_maps(&Some(base), &Some(other)).unwrap();
+ assert_eq!(result["a"], "1");
+ assert_eq!(result["b"], "2");
+ assert_eq!(result["shared"], "other");
+ }
+}
diff --git a/src/config/user/tests.rs b/src/config/user/tests.rs
index 2eab5a9c7..57ecdcc09 100644
--- a/src/config/user/tests.rs
+++ b/src/config/user/tests.rs
@@ -2020,7 +2020,7 @@ fn test_valid_user_config_keys_all_deserialize() {
"worktree-path" => {
scalar_lines.push(format!("{key} = \"test-value\""));
}
- "list" | "commit" | "merge" | "switch" | "select" | "commit-generation" => {
+ "list" | "commit" | "merge" | "switch" | "select" | "commit-generation" | "aliases" => {
// Table sections with minimal content
table_lines.push(format!("[{key}]"));
}
diff --git a/src/main.rs b/src/main.rs
index db63cef6c..370669adb 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -711,6 +711,9 @@ fn main() {
commit,
clobber,
} => step_relocate(branches, dry_run, commit, clobber),
+ StepCommand::External(args) => {
+ commands::AliasOptions::parse(args).and_then(commands::step_alias)
+ }
},
Commands::Hook { action } => handle_hook_command(action),
#[cfg(unix)]
diff --git a/tests/integration_tests/mod.rs b/tests/integration_tests/mod.rs
index 2f8155c60..9cd75106a 100644
--- a/tests/integration_tests/mod.rs
+++ b/tests/integration_tests/mod.rs
@@ -54,6 +54,7 @@ pub mod shell_wrapper;
pub mod snapshot_formatting_guard;
pub mod spacing_edge_cases;
pub mod statusline;
+pub mod step_alias;
pub mod step_copy_ignored;
pub mod step_diff;
pub mod step_promote;
diff --git a/tests/integration_tests/step_alias.rs b/tests/integration_tests/step_alias.rs
new file mode 100644
index 000000000..be2e16893
--- /dev/null
+++ b/tests/integration_tests/step_alias.rs
@@ -0,0 +1,442 @@
+//! Integration tests for `wt step <alias>`
+
+use crate::common::{TestRepo, make_snapshot_cmd, repo, setup_snapshot_settings};
+use insta_cmd::assert_cmd_snapshot;
+use rstest::rstest;
+use std::io::Write;
+use std::process::Stdio;
+
+/// Alias from project config runs with template expansion (--yes bypasses approval)
+#[rstest]
+fn test_step_alias_from_project_config(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+hello = "echo Hello from {{ branch }}"
+"#,
+ );
+ 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",
+ &["hello", "--yes"],
+ Some(&feature_path),
+ ));
+}
+
+/// --dry-run shows the expanded command without running it (no approval needed)
+#[rstest]
+fn test_step_alias_dry_run(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+hello = "echo Hello from {{ branch }}"
+"#,
+ );
+ repo.commit("Add alias config");
+ let feature_path = repo.add_worktree("feature");
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ // No --yes needed: --dry-run skips approval
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["hello", "--dry-run"],
+ Some(&feature_path),
+ ));
+}
+
+/// Unknown alias shows error with available aliases
+#[rstest]
+fn test_step_alias_unknown_with_available(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+hello = "echo Hello"
+deploy = "make deploy"
+"#,
+ );
+ 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",
+ &["nonexistent"],
+ Some(&feature_path),
+ ));
+}
+
+/// Unknown step command with no aliases configured
+#[rstest]
+fn test_step_alias_unknown_no_aliases(mut repo: TestRepo) {
+ 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"],
+ Some(&feature_path),
+ ));
+}
+
+/// --var flag adds extra template variables (--yes bypasses approval)
+#[rstest]
+fn test_step_alias_with_var(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+greet = "echo Hello {{ name }} from {{ branch }}"
+"#,
+ );
+ 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",
+ &["greet", "--dry-run", "--var", "name=World", "--yes"],
+ Some(&feature_path),
+ ));
+}
+
+/// Alias command failure propagates exit code (--yes bypasses approval)
+#[rstest]
+fn test_step_alias_exit_code(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+fail = "exit 42"
+"#,
+ );
+ 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",
+ &["fail", "--yes"],
+ Some(&feature_path),
+ ));
+}
+
+/// Alias from user config works
+#[rstest]
+fn test_step_alias_from_user_config(mut repo: TestRepo) {
+ let feature_path = repo.add_worktree("feature");
+ repo.write_test_config(
+ r#"
+[aliases]
+greet = "echo Greetings from {{ branch }}"
+"#,
+ );
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["greet"],
+ Some(&feature_path),
+ ));
+}
+
+/// Shadowed aliases are filtered from the "available" list in error messages
+#[rstest]
+fn test_step_alias_shadows_builtin(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+commit = "echo custom-commit"
+hello = "echo hello"
+"#,
+ );
+ repo.commit("Add alias config");
+ let feature_path = repo.add_worktree("feature");
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ // "commit" is shadowed by the built-in and should not appear in available list
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["nonexistent"],
+ Some(&feature_path),
+ ));
+}
+
+/// User config aliases merge with project config aliases
+#[rstest]
+fn test_step_alias_merge_user_and_project(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+project-cmd = "echo from-project"
+shared = "echo project-version"
+"#,
+ );
+ repo.commit("Add alias config");
+ let feature_path = repo.add_worktree("feature");
+ repo.write_test_config(
+ r#"
+[aliases]
+user-cmd = "echo from-user"
+shared = "echo user-version"
+"#,
+ );
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ // User alias available
+ assert_cmd_snapshot!(
+ "user_alias",
+ make_snapshot_cmd(
+ &repo,
+ "step",
+ &["user-cmd", "--dry-run"],
+ Some(&feature_path),
+ )
+ );
+
+ // Project alias available (--yes bypasses approval for project-config aliases)
+ assert_cmd_snapshot!(
+ "project_alias",
+ make_snapshot_cmd(
+ &repo,
+ "step",
+ &["project-cmd", "--dry-run", "--yes"],
+ Some(&feature_path),
+ )
+ );
+
+ // User overrides project on collision (user config = trusted, no approval needed)
+ assert_cmd_snapshot!(
+ "user_overrides_project",
+ make_snapshot_cmd(&repo, "step", &["shared", "--dry-run"], Some(&feature_path),)
+ );
+}
+
+// ============================================================================
+// Approval tests
+// ============================================================================
+
+/// Helper for alias approval snapshot tests
+fn snapshot_alias_approval(
+ test_name: &str,
+ repo: &TestRepo,
+ alias_args: &[&str],
+ approve: bool,
+ cwd: Option<&std::path::Path>,
+) {
+ let mut cmd = make_snapshot_cmd(repo, "step", alias_args, cwd);
+ cmd.stdin(Stdio::piped())
+ .stdout(Stdio::piped())
+ .stderr(Stdio::piped());
+
+ let mut child = cmd.spawn().unwrap();
+
+ {
+ let stdin = child.stdin.as_mut().unwrap();
+ let response = if approve { b"y\n" } else { b"n\n" };
+ stdin.write_all(response).unwrap();
+ }
+
+ let output = child.wait_with_output().unwrap();
+
+ let stdout = String::from_utf8_lossy(&output.stdout);
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ let combined = format!(
+ "exit_code: {}\n----- stdout -----\n{}\n----- stderr -----\n{}",
+ output.status.code().unwrap_or(-1),
+ stdout,
+ stderr
+ );
+
+ insta::assert_snapshot!(test_name, combined);
+}
+
+/// Project-config alias prompts for approval in non-TTY (fails with hint)
+#[rstest]
+fn test_alias_approval_project_config_prompts(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+deploy = "echo deploying {{ branch }}"
+"#,
+ );
+ repo.commit("Add alias config");
+ let feature_path = repo.add_worktree("feature");
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ // Without --yes, project alias triggers approval prompt (fails in non-TTY)
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["deploy"],
+ Some(&feature_path),
+ ));
+}
+
+/// Already-approved project-config alias runs without re-prompting
+#[rstest]
+fn test_alias_approval_already_approved(mut repo: TestRepo) {
+ // Remove origin so worktrunk uses directory name as project identifier
+ repo.run_git(&["remote", "remove", "origin"]);
+
+ repo.write_project_config(
+ r#"
+[aliases]
+deploy = "echo deploying {{ branch }}"
+"#,
+ );
+ repo.commit("Add alias config");
+ let feature_path = repo.add_worktree("feature");
+
+ // Pre-approve the alias command
+ repo.write_test_approvals(&format!(
+ r#"[projects.'{}']
+approved-commands = ["echo deploying {{{{ branch }}}}"]
+"#,
+ repo.project_id()
+ ));
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ // Should run without prompting
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["deploy"],
+ Some(&feature_path),
+ ));
+}
+
+/// User-config alias skips approval entirely
+#[rstest]
+fn test_alias_approval_user_config_skips(mut repo: TestRepo) {
+ let feature_path = repo.add_worktree("feature");
+ repo.write_test_config(
+ r#"
+[aliases]
+deploy = "echo deploying from user config"
+"#,
+ );
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ // User alias runs without approval
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["deploy"],
+ Some(&feature_path),
+ ));
+}
+
+/// User override of project alias skips approval (user is trusted)
+#[rstest]
+fn test_alias_approval_user_override_skips(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+deploy = "echo UNTRUSTED project deploy"
+"#,
+ );
+ repo.commit("Add alias config");
+ let feature_path = repo.add_worktree("feature");
+ repo.write_test_config(
+ r#"
+[aliases]
+deploy = "echo trusted user deploy"
+"#,
+ );
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ // User override runs without approval — the user version is trusted
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["deploy"],
+ Some(&feature_path),
+ ));
+}
+
+/// --yes bypasses approval for project-config alias without saving
+#[rstest]
+fn test_alias_approval_yes_bypasses(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+deploy = "echo deploying"
+"#,
+ );
+ repo.commit("Add alias config");
+ let feature_path = repo.add_worktree("feature");
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ // First run with --yes succeeds
+ assert_cmd_snapshot!(
+ "alias_approval_yes_first_run",
+ make_snapshot_cmd(&repo, "step", &["deploy", "--yes"], Some(&feature_path),)
+ );
+
+ // Second run without --yes should still prompt (--yes doesn't save approval)
+ assert_cmd_snapshot!(
+ "alias_approval_yes_second_run_prompts",
+ make_snapshot_cmd(&repo, "step", &["deploy"], Some(&feature_path),)
+ );
+}
+
+/// Declining approval prevents alias execution
+#[rstest]
+fn test_alias_approval_decline(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+deploy = "echo deploying"
+"#,
+ );
+ repo.commit("Add alias config");
+ let feature_path = repo.add_worktree("feature");
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ snapshot_alias_approval(
+ "alias_approval_decline",
+ &repo,
+ &["deploy"],
+ false,
+ Some(&feature_path),
+ );
+}
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index dce90dc7c..cc8cfb5b5 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -12,6 +12,7 @@ info:
GIT_EDITOR: ""
LANG: C
LC_ALL: C
+ NO_COLOR: ""
PSModulePath: ""
RUST_LOG: warn
SHELL: ""
@@ -142,6 +143,16 @@ Creates ~/.config/worktrunk/config.toml with the following content:
# # Lower values show the TUI faster; 0 disables timeouts
# # timeout-ms = 200
#
+ # ### Aliases
+ #
+ # Command templates that run with `wt step <name>`. See `wt step` aliases (https://worktrunk.dev/step/#aliases) for usage and flags.
+ #
+ # [aliases]
+ # greet = "echo Hello from {{ branch }}"
+ # url = "echo http://localhost:{{ branch | hash_port }}"
+ #
+ # Aliases defined here apply to all projects. For project-specific aliases, use the project config (https://worktrunk.dev/config/#project-configuration) `[aliases]` section instead.
+ #
# ### User project-specific settings
#
# For context:
@@ -154,13 +165,14 @@ Creates ~/.config/worktrunk/config.toml with the following content:
#
# #### Setting overrides (Experimental)
#
- # Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run.
+ # Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run. Aliases merge — per-project aliases override global aliases on name collision.
#
# [projects."github.com/user/repo"]
# worktree-path = ".worktrees/{{ branch | sanitize }}"
# list.full = true
# merge.squash = false
# post-create.env = "cp .env.example .env"
+ # aliases.deploy = "make deploy BRANCH={{ branch }}"
#
# ### Custom prompt templates
#
@@ -342,6 +354,16 @@ With --project, creates .config/wt.toml in the current repositor
# pre-remove = "docker compose down"

# ============================================================================
+ # Aliases (experimental) — run with `wt step <name>`
+ # ============================================================================
+ # Command templates that support the same variables as hooks.
+ # Project-config aliases require command approval on first run.
+ #
+ # [aliases]
+ # deploy = "make deploy BRANCH={{ branch }}"
+ # url = "echo http://localhost:{{ branch | hash_port }}"
+ 
+ # ============================================================================
# Dev Server URL (shown in `wt list`)
# ============================================================================
# [list]
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 78dd35894..c13daeea4 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -11,6 +11,7 @@ info:
GIT_EDITOR: ""
LANG: C
LC_ALL: C
+ NO_COLOR: ""
PSModulePath: ""
RUST_LOG: warn
SHELL: ""
@@ -187,6 +188,16 @@ Configuration for wt switch interactive picker.
# Lower values show the TUI faster; 0 disables timeouts
# timeout-ms = 200
+Aliases
+
+Command templates that run with wt step <name>. See wt step aliases for usage and flags.
+
+ [aliases]
+ greet = "echo Hello from {{ branch }}"
+ url = "echo http://localhost:{{ branch | hash_port }}"
+
+Aliases defined here apply to all projects. For project-specific aliases, use the project config [aliases] section instead.
+
User project-specific settings
For context:
@@ -199,13 +210,14 @@ Entries are keyed by project identifier (e.g., github.com/user/repo).
Setting overrides (Experimental)
-Override global user config for a specific project. Scalar values (like worktree-path) replace the global value. Hooks append — both global and per-project hooks run.
+Override global user config for a specific project. Scalar values (like worktree-path) replace the global value. Hooks append — both global and per-project hooks run. Aliases merge — per-project aliases override global aliases on name collision.
[projects."github.com/user/repo"]
worktree-path = ".worktrees/{{ branch | sanitize }}"
list.full = true
merge.squash = false
post-create.env = "cp .env.example .env"
+ aliases.deploy = "make deploy BRANCH={{ branch }}"
Custom prompt templates
@@ -310,6 +322,11 @@ See wt hook for hook types, execution order, template variables, and exa
# Override CI platform detection for self-hosted instances
[ci]
platform = "github" # or "gitlab"
+ 
+ # Command aliases (run with wt step <name>)
+ [aliases]
+ deploy = "make deploy BRANCH={{ branch }}"
+ test = "cargo test"
SHELL INTEGRATION
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
index a1f6242ed..6bae8832b 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -11,6 +11,7 @@ info:
GIT_EDITOR: ""
LANG: C
LC_ALL: C
+ NO_COLOR: ""
PSModulePath: ""
RUST_LOG: warn
SHELL: ""
@@ -87,6 +88,25 @@ Manual merge workflow with review between steps:
- promote — [experimental] Put a branch into the main worktree
- prune — Remove worktrees and branches merged into the default branch
- relocate — [experimental] Move worktrees to expected paths
+- <alias> — [experimental] Run a configured command alias
+
+Aliases
+
+Custom command templates configured in user config (~/.config/worktrunk/config.toml) or project config (.config/wt.toml). Aliases support the same template variables as hooks.
+
+ # .config/wt.toml
+ [aliases]
+ deploy = "make deploy BRANCH={{ branch }}"
+ port = "echo http://localhost:{{ branch | hash_port }}"
+
+ wt step deploy # run the alias
+ wt step deploy --dry-run # show expanded command
+ wt step deploy --var env=staging # pass extra template variables
+ wt step deploy --yes # skip approval prompt
+
+When defined in both user and project config, user aliases take precedence. Project-config aliases require command approval on first run (same as project hooks). User-config aliases are trusted.
+
+Alias names that match a built-in step command (commit, squash, etc.) are shadowed by the built-in and will never run.
See also
diff --git a/tests/snapshots/integration__integration_tests__step_alias__alias_approval_already_approved.snap b/tests/snapshots/integration__integration_tests__step_alias__alias_approval_already_approved.snap
new file mode 100644
index 000000000..431727469
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__alias_approval_already_approved.snap
@@ -0,0 +1,46 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - deploy
+ 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: ""
+ 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_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+◎ Running alias deploy
+deploying feature
diff --git a/tests/snapshots/integration__integration_tests__step_alias__alias_approval_decline.snap b/tests/snapshots/integration__integration_tests__step_alias__alias_approval_decline.snap
new file mode 100644
index 000000000..e4e6c8da8
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__alias_approval_decline.snap
@@ -0,0 +1,13 @@
+---
+source: tests/integration_tests/step_alias.rs
+expression: combined
+---
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+▲ origin needs approval to execute 1 command:
+○ alias deploy:
+  echo deploying
+✗ Cannot prompt for approval in non-interactive environment
+↳ To skip prompts in CI/CD, add --yes; to pre-approve commands, run wt hook approvals add
diff --git a/tests/snapshots/integration__integration_tests__step_alias__alias_approval_project_config_prompts.snap b/tests/snapshots/integration__integration_tests__step_alias__alias_approval_project_config_prompts.snap
new file mode 100644
index 000000000..313e914bd
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__alias_approval_project_config_prompts.snap
@@ -0,0 +1,49 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - deploy
+ 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: ""
+ 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_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 deploying {{ branch }}
+✗ Cannot prompt for approval in non-interactive environment
+↳ To skip prompts in CI/CD, add --yes; to pre-approve commands, run wt hook approvals add
diff --git a/tests/snapshots/integration__integration_tests__step_alias__alias_approval_user_config_skips.snap b/tests/snapshots/integration__integration_tests__step_alias__alias_approval_user_config_skips.snap
new file mode 100644
index 000000000..29472ad18
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__alias_approval_user_config_skips.snap
@@ -0,0 +1,46 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - deploy
+ 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: ""
+ 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_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+◎ Running alias deploy
+deploying from user config
diff --git a/tests/snapshots/integration__integration_tests__step_alias__alias_approval_user_override_skips.snap b/tests/snapshots/integration__integration_tests__step_alias__alias_approval_user_override_skips.snap
new file mode 100644
index 000000000..cbe21df0f
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__alias_approval_user_override_skips.snap
@@ -0,0 +1,46 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - deploy
+ 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: ""
+ 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_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+◎ Running alias deploy
+trusted user deploy
diff --git a/tests/snapshots/integration__integration_tests__step_alias__alias_approval_yes_first_run.snap b/tests/snapshots/integration__integration_tests__step_alias__alias_approval_yes_first_run.snap
new file mode 100644
index 000000000..6bcc55ed2
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__alias_approval_yes_first_run.snap
@@ -0,0 +1,47 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - deploy
+ - "--yes"
+ 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: ""
+ 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_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+◎ Running alias deploy
+deploying
diff --git a/tests/snapshots/integration__integration_tests__step_alias__alias_approval_yes_second_run_prompts.snap b/tests/snapshots/integration__integration_tests__step_alias__alias_approval_yes_second_run_prompts.snap
new file mode 100644
index 000000000..d575c01ce
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__alias_approval_yes_second_run_prompts.snap
@@ -0,0 +1,49 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - deploy
+ 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: ""
+ 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_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 deploying
+✗ Cannot prompt for approval in non-interactive environment
+↳ To skip prompts in CI/CD, add --yes; to pre-approve commands, run wt hook approvals add
diff --git a/tests/snapshots/integration__integration_tests__step_alias__project_alias.snap b/tests/snapshots/integration__integration_tests__step_alias__project_alias.snap
new file mode 100644
index 000000000..38b7b01b4
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__project_alias.snap
@@ -0,0 +1,47 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - project-cmd
+ - "--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: ""
+ 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_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+○ Alias project-cmd would run:
+  echo from-project
diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_alias_dry_run.snap b/tests/snapshots/integration__integration_tests__step_alias__step_alias_dry_run.snap
new file mode 100644
index 000000000..6f748ff00
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__step_alias_dry_run.snap
@@ -0,0 +1,47 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - hello
+ - "--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: ""
+ 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_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+○ Alias hello would run:
+  echo Hello from feature
diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_alias_exit_code.snap b/tests/snapshots/integration__integration_tests__step_alias__step_alias_exit_code.snap
new file mode 100644
index 000000000..6a80af606
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__step_alias_exit_code.snap
@@ -0,0 +1,45 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - fail
+ 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: ""
+ 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_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 42
+----- stdout -----
+
+----- stderr -----
+◎ Running alias fail
diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_alias_from_project_config.snap b/tests/snapshots/integration__integration_tests__step_alias__step_alias_from_project_config.snap
new file mode 100644
index 000000000..106739c51
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__step_alias_from_project_config.snap
@@ -0,0 +1,46 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - hello
+ 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: ""
+ 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_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+◎ Running alias hello
+Hello from feature
diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_alias_from_user_config.snap b/tests/snapshots/integration__integration_tests__step_alias__step_alias_from_user_config.snap
new file mode 100644
index 000000000..de1d6c9a4
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__step_alias_from_user_config.snap
@@ -0,0 +1,46 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - greet
+ 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: ""
+ 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_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+◎ Running alias greet
+Greetings from feature
diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_alias_shadows_builtin.snap b/tests/snapshots/integration__integration_tests__step_alias__step_alias_shadows_builtin.snap
new file mode 100644
index 000000000..ffff1269e
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__step_alias_shadows_builtin.snap
@@ -0,0 +1,45 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - nonexistent
+ 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: ""
+ 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_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+✗ Unknown alias 'nonexistent' (available: hello)
diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_alias_unknown_no_aliases.snap b/tests/snapshots/integration__integration_tests__step_alias__step_alias_unknown_no_aliases.snap
new file mode 100644
index 000000000..c1862696b
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__step_alias_unknown_no_aliases.snap
@@ -0,0 +1,45 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - deploy
+ 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: ""
+ 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_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+✗ Unknown step command 'deploy' (no aliases configured)
diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_alias_unknown_with_available.snap b/tests/snapshots/integration__integration_tests__step_alias__step_alias_unknown_with_available.snap
new file mode 100644
index 000000000..a7b67cd90
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__step_alias_unknown_with_available.snap
@@ -0,0 +1,45 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - nonexistent
+ 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: ""
+ 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_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+✗ Unknown alias 'nonexistent' (available: deploy, hello)
diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_alias_with_var.snap b/tests/snapshots/integration__integration_tests__step_alias__step_alias_with_var.snap
new file mode 100644
index 000000000..631ef4789
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__step_alias_with_var.snap
@@ -0,0 +1,49 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - greet
+ - "--dry-run"
+ - "--var"
+ - name=World
+ 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: ""
+ 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_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+○ Alias greet would run:
+  echo Hello World from feature
diff --git a/tests/snapshots/integration__integration_tests__step_alias__user_alias.snap b/tests/snapshots/integration__integration_tests__step_alias__user_alias.snap
new file mode 100644
index 000000000..2e92685d2
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__user_alias.snap
@@ -0,0 +1,47 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - user-cmd
+ - "--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: ""
+ 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_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+○ Alias user-cmd would run:
+  echo from-user
diff --git a/tests/snapshots/integration__integration_tests__step_alias__user_overrides_project.snap b/tests/snapshots/integration__integration_tests__step_alias__user_overrides_project.snap
new file mode 100644
index 000000000..ef7cdcdfa
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__user_overrides_project.snap
@@ -0,0 +1,47 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - shared
+ - "--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: ""
+ 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_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+○ Alias shared would run:
+  echo user-version