From 2b2ef39f36f90aa80753313c9e76c1254374078d Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Wed, 17 Dec 2025 10:28:24 -0600
Subject: [PATCH 1/8] fix(cli): rename `alias` command to `tool-alias` and
 write to `[tool_alias]` config
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Rename CLI command from `alias` to `tool-alias` (keeping `alias` as hidden alias for backwards compatibility)
- Change `set_alias` and `set_backend_alias` to write to `[tool_alias]` section instead of deprecated `[alias]`
- Update `remove_alias` and `remove_backend_alias` to check both sections for backwards compatibility
- Update tests to use `[tool_alias]` section

This fixes the confusing situation where the deprecation warning for `[alias]` in config files told users to use `[tool_alias]`, but the CLI command `mise alias` was writing to the deprecated `[alias]` section.

Fixes #7353

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/cli/alias/mod.rs                |  5 ++-
 src/cli/mod.rs                      |  4 +-
 src/config/config_file/mise_toml.rs | 64 +++++++++++++++++------------
 3 files changed, 42 insertions(+), 31 deletions(-)

diff --git a/src/cli/alias/mod.rs b/src/cli/alias/mod.rs
index 50480f26e9..e3809d2d8e 100644
--- a/src/cli/alias/mod.rs
+++ b/src/cli/alias/mod.rs
@@ -10,8 +10,9 @@ mod unset;
 
 #[derive(Debug, clap::Args)]
 #[clap(
-    about = "Manage version aliases.",
-    visible_alias = "a",
+    name = "tool-alias",
+    about = "Manage tool version aliases.",
+    alias = "alias",
     alias = "aliases"
 )]
 pub struct Alias {
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index ff757fd7bd..3fc5a50041 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -191,7 +191,7 @@ pub struct Cli {
 #[strum(serialize_all = "kebab-case")]
 pub enum Commands {
     Activate(activate::Activate),
-    Alias(Box<alias::Alias>),
+    ToolAlias(Box<alias::Alias>),
     Asdf(asdf::Asdf),
     Backends(backends::Backends),
     BinPaths(bin_paths::BinPaths),
@@ -257,7 +257,7 @@ impl Commands {
     pub async fn run(self) -> Result<()> {
         match self {
             Self::Activate(cmd) => cmd.run(),
-            Self::Alias(cmd) => cmd.run().await,
+            Self::ToolAlias(cmd) => cmd.run().await,
             Self::Asdf(cmd) => cmd.run().await,
             Self::Backends(cmd) => cmd.run().await,
             Self::BinPaths(cmd) => cmd.run().await,
diff --git a/src/config/config_file/mise_toml.rs b/src/config/config_file/mise_toml.rs
index 597c39dd4f..6764c2d028 100644
--- a/src/config/config_file/mise_toml.rs
+++ b/src/config/config_file/mise_toml.rs
@@ -209,7 +209,7 @@ impl MiseToml {
         self.doc_mut()?
             .get_mut()
             .unwrap()
-            .entry("alias")
+            .entry("tool_alias")
             .or_insert_with(table)
             .as_table_like_mut()
             .unwrap()
@@ -218,7 +218,7 @@ impl MiseToml {
     }
 
     pub fn set_alias(&mut self, fa: &BackendArg, from: &str, to: &str) -> eyre::Result<()> {
-        self.alias
+        self.tool_alias
             .entry(fa.short.to_string())
             .or_default()
             .versions
@@ -226,7 +226,7 @@ impl MiseToml {
         self.doc_mut()?
             .get_mut()
             .unwrap()
-            .entry("alias")
+            .entry("tool_alias")
             .or_insert_with(table)
             .as_table_like_mut()
             .unwrap()
@@ -245,42 +245,52 @@ impl MiseToml {
     pub fn remove_backend_alias(&mut self, fa: &BackendArg) -> eyre::Result<()> {
         let mut doc = self.doc_mut()?;
         let doc = doc.get_mut().unwrap();
-        if let Some(aliases) = doc.get_mut("alias").and_then(|v| v.as_table_mut()) {
-            aliases.remove(&fa.short);
-            if aliases.is_empty() {
-                doc.as_table_mut().remove("alias");
+        // Remove from both tool_alias and deprecated alias sections
+        for section in ["tool_alias", "alias"] {
+            if let Some(aliases) = doc.get_mut(section).and_then(|v| v.as_table_mut()) {
+                aliases.remove(&fa.short);
+                if aliases.is_empty() {
+                    doc.as_table_mut().remove(section);
+                }
             }
         }
         Ok(())
     }
 
     pub fn remove_alias(&mut self, fa: &BackendArg, from: &str) -> eyre::Result<()> {
-        if let Some(aliases) = self.alias.get_mut(&fa.short) {
-            aliases.versions.shift_remove(from);
-            if aliases.versions.is_empty() && aliases.backend.is_none() {
-                self.alias.shift_remove(&fa.short);
+        // Remove from both tool_alias and deprecated alias in memory
+        for alias_map in [&mut self.tool_alias, &mut self.alias] {
+            if let Some(aliases) = alias_map.get_mut(&fa.short) {
+                aliases.versions.shift_remove(from);
+                if aliases.versions.is_empty() && aliases.backend.is_none() {
+                    alias_map.shift_remove(&fa.short);
+                }
             }
         }
         let mut doc = self.doc_mut()?;
         let doc = doc.get_mut().unwrap();
-        if let Some(aliases) = doc.get_mut("alias").and_then(|v| v.as_table_mut()) {
-            if let Some(alias) = aliases
-                .get_mut(&fa.to_string())
-                .and_then(|v| v.as_table_mut())
-            {
-                if let Some(versions) = alias.get_mut("versions").and_then(|v| v.as_table_mut()) {
-                    versions.remove(from);
-                    if versions.is_empty() {
-                        alias.remove("versions");
+        // Remove from both tool_alias and deprecated alias sections in doc
+        for section in ["tool_alias", "alias"] {
+            if let Some(aliases) = doc.get_mut(section).and_then(|v| v.as_table_mut()) {
+                if let Some(alias) = aliases
+                    .get_mut(&fa.to_string())
+                    .and_then(|v| v.as_table_mut())
+                {
+                    if let Some(versions) = alias.get_mut("versions").and_then(|v| v.as_table_mut())
+                    {
+                        versions.remove(from);
+                        if versions.is_empty() {
+                            alias.remove("versions");
+                        }
+                    }
+                    if alias.is_empty() {
+                        aliases.remove(&fa.to_string());
                     }
                 }
-                if alias.is_empty() {
-                    aliases.remove(&fa.to_string());
+                if aliases.is_empty() {
+                    doc.as_table_mut().remove(section);
                 }
             }
-            if aliases.is_empty() {
-                doc.as_table_mut().remove("alias");
-            }
         }
         Ok(())
     }
@@ -1957,7 +1967,7 @@ mod tests {
         file::write(
             &p,
             formatdoc! {r#"
-            [alias.node.versions]
+            [tool_alias.node.versions]
             16 = "16.0.0"
             18 = "18.0.0"
         "#},
@@ -1970,7 +1980,7 @@ mod tests {
         cf.set_alias(&node, "20", "20.0.0").unwrap();
         cf.set_alias(&python, "3.10", "3.10.0").unwrap();
 
-        assert_debug_snapshot!(cf.alias);
+        assert_debug_snapshot!(cf.tool_alias);
         let cf: Box<dyn ConfigFile> = Box::new(cf);
         assert_snapshot!(cf);
         file::remove_file(&p).unwrap();

From 9ed71336b315a5d0a447469966bbf6b0adb973f3 Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Wed, 17 Dec 2025 10:34:07 -0600
Subject: [PATCH 2/8] chore: hide tool-alias command from help

---
 src/cli/alias/mod.rs | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/cli/alias/mod.rs b/src/cli/alias/mod.rs
index e3809d2d8e..7c7fe24639 100644
--- a/src/cli/alias/mod.rs
+++ b/src/cli/alias/mod.rs
@@ -13,7 +13,8 @@ mod unset;
     name = "tool-alias",
     about = "Manage tool version aliases.",
     alias = "alias",
-    alias = "aliases"
+    alias = "aliases",
+    hide = true
 )]
 pub struct Alias {
     #[clap(subcommand)]

From 3445ea1cfca57ca4548cf2ab89cbf2578d0f68bd Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Wed, 17 Dec 2025 10:37:29 -0600
Subject: [PATCH 3/8] fix: keep tool-alias visible, only hide alias/aliases
 aliases

---
 src/cli/alias/mod.rs | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/cli/alias/mod.rs b/src/cli/alias/mod.rs
index 7c7fe24639..e3809d2d8e 100644
--- a/src/cli/alias/mod.rs
+++ b/src/cli/alias/mod.rs
@@ -13,8 +13,7 @@ mod unset;
     name = "tool-alias",
     about = "Manage tool version aliases.",
     alias = "alias",
-    alias = "aliases",
-    hide = true
+    alias = "aliases"
 )]
 pub struct Alias {
     #[clap(subcommand)]

From f26bb6955b73a535e47a61883c0b109c3aeca7dc Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Wed, 17 Dec 2025 16:45:04 +0000
Subject: [PATCH 4/8] [autofix.ci] apply automated fixes

---
 docs/.vitepress/cli_commands.ts         | 34 +++++++++++------------
 docs/cli/alias.md                       | 25 -----------------
 docs/cli/index.md                       | 10 +++----
 docs/cli/tool-alias.md                  | 24 ++++++++++++++++
 docs/cli/{alias => tool-alias}/get.md   |  6 ++--
 docs/cli/{alias => tool-alias}/ls.md    |  6 ++--
 docs/cli/{alias => tool-alias}/set.md   |  6 ++--
 docs/cli/{alias => tool-alias}/unset.md |  6 ++--
 man/man1/mise.1                         | 37 ++++++++++++-------------
 mise.usage.kdl                          |  5 ++--
 xtasks/fig/src/mise.ts                  |  4 +--
 11 files changed, 79 insertions(+), 84 deletions(-)
 delete mode 100644 docs/cli/alias.md
 create mode 100644 docs/cli/tool-alias.md
 rename docs/cli/{alias => tool-alias}/get.md (62%)
 rename docs/cli/{alias => tool-alias}/ls.md (72%)
 rename docs/cli/{alias => tool-alias}/set.md (70%)
 rename docs/cli/{alias => tool-alias}/unset.md (65%)

diff --git a/docs/.vitepress/cli_commands.ts b/docs/.vitepress/cli_commands.ts
index 12b8a787f3..281770d17f 100644
--- a/docs/.vitepress/cli_commands.ts
+++ b/docs/.vitepress/cli_commands.ts
@@ -11,23 +11,6 @@ export const commands: { [key: string]: Command } = {
   activate: {
     hide: false,
   },
-  alias: {
-    hide: false,
-    subcommands: {
-      get: {
-        hide: false,
-      },
-      ls: {
-        hide: false,
-      },
-      set: {
-        hide: false,
-      },
-      unset: {
-        hide: false,
-      },
-    },
-  },
   asdf: {
     hide: true,
   },
@@ -306,6 +289,23 @@ export const commands: { [key: string]: Command } = {
   tool: {
     hide: false,
   },
+  "tool-alias": {
+    hide: false,
+    subcommands: {
+      get: {
+        hide: false,
+      },
+      ls: {
+        hide: false,
+      },
+      set: {
+        hide: false,
+      },
+      unset: {
+        hide: false,
+      },
+    },
+  },
   "tool-stub": {
     hide: false,
   },
diff --git a/docs/cli/alias.md b/docs/cli/alias.md
deleted file mode 100644
index 989c7978f2..0000000000
--- a/docs/cli/alias.md
+++ /dev/null
@@ -1,25 +0,0 @@
-<!-- @generated by usage-cli from usage spec -->
-# `mise alias`
-
-- **Usage**: `mise alias [-p --plugin <PLUGIN>] [--no-header] <SUBCOMMAND>`
-- **Aliases**: `a`
-- **Source code**: [`src/cli/alias/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/alias/mod.rs)
-
-Manage version aliases.
-
-## Flags
-
-### `-p --plugin <PLUGIN>`
-
-filter aliases by plugin
-
-### `--no-header`
-
-Don't show table header
-
-## Subcommands
-
-- [`mise alias get <PLUGIN> <ALIAS>`](/cli/alias/get.md)
-- [`mise alias ls [--no-header] [TOOL]`](/cli/alias/ls.md)
-- [`mise alias set <ARGS>…`](/cli/alias/set.md)
-- [`mise alias unset <PLUGIN> [ALIAS]`](/cli/alias/unset.md)
diff --git a/docs/cli/index.md b/docs/cli/index.md
index aaac5a215e..94ea805766 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -68,11 +68,11 @@ Can also use `MISE_NO_CONFIG=1`
 ## Subcommands
 
 - [`mise activate [FLAGS] [SHELL_TYPE]`](/cli/activate.md)
-- [`mise alias [-p --plugin <PLUGIN>] [--no-header] <SUBCOMMAND>`](/cli/alias.md)
-- [`mise alias get <PLUGIN> <ALIAS>`](/cli/alias/get.md)
-- [`mise alias ls [--no-header] [TOOL]`](/cli/alias/ls.md)
-- [`mise alias set <ARGS>…`](/cli/alias/set.md)
-- [`mise alias unset <PLUGIN> [ALIAS]`](/cli/alias/unset.md)
+- [`mise tool-alias [-p --plugin <PLUGIN>] [--no-header] <SUBCOMMAND>`](/cli/tool-alias.md)
+- [`mise tool-alias get <PLUGIN> <ALIAS>`](/cli/tool-alias/get.md)
+- [`mise tool-alias ls [--no-header] [TOOL]`](/cli/tool-alias/ls.md)
+- [`mise tool-alias set <ARGS>…`](/cli/tool-alias/set.md)
+- [`mise tool-alias unset <PLUGIN> [ALIAS]`](/cli/tool-alias/unset.md)
 - [`mise backends <SUBCOMMAND>`](/cli/backends.md)
 - [`mise backends ls`](/cli/backends/ls.md)
 - [`mise bin-paths [TOOL@VERSION]…`](/cli/bin-paths.md)
diff --git a/docs/cli/tool-alias.md b/docs/cli/tool-alias.md
new file mode 100644
index 0000000000..33488651de
--- /dev/null
+++ b/docs/cli/tool-alias.md
@@ -0,0 +1,24 @@
+<!-- @generated by usage-cli from usage spec -->
+# `mise tool-alias`
+
+- **Usage**: `mise tool-alias [-p --plugin <PLUGIN>] [--no-header] <SUBCOMMAND>`
+- **Source code**: [`src/cli/tool_alias/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/tool_alias/mod.rs)
+
+Manage tool version aliases.
+
+## Flags
+
+### `-p --plugin <PLUGIN>`
+
+filter aliases by plugin
+
+### `--no-header`
+
+Don't show table header
+
+## Subcommands
+
+- [`mise tool-alias get <PLUGIN> <ALIAS>`](/cli/tool-alias/get.md)
+- [`mise tool-alias ls [--no-header] [TOOL]`](/cli/tool-alias/ls.md)
+- [`mise tool-alias set <ARGS>…`](/cli/tool-alias/set.md)
+- [`mise tool-alias unset <PLUGIN> [ALIAS]`](/cli/tool-alias/unset.md)
diff --git a/docs/cli/alias/get.md b/docs/cli/tool-alias/get.md
similarity index 62%
rename from docs/cli/alias/get.md
rename to docs/cli/tool-alias/get.md
index 1f7cf4fef6..b4fab982f3 100644
--- a/docs/cli/alias/get.md
+++ b/docs/cli/tool-alias/get.md
@@ -1,8 +1,8 @@
 <!-- @generated by usage-cli from usage spec -->
-# `mise alias get`
+# `mise tool-alias get`
 
-- **Usage**: `mise alias get <PLUGIN> <ALIAS>`
-- **Source code**: [`src/cli/alias/get.rs`](https://github.com/jdx/mise/blob/main/src/cli/alias/get.rs)
+- **Usage**: `mise tool-alias get <PLUGIN> <ALIAS>`
+- **Source code**: [`src/cli/tool_alias/get.rs`](https://github.com/jdx/mise/blob/main/src/cli/tool_alias/get.rs)
 
 Show an alias for a plugin
 
diff --git a/docs/cli/alias/ls.md b/docs/cli/tool-alias/ls.md
similarity index 72%
rename from docs/cli/alias/ls.md
rename to docs/cli/tool-alias/ls.md
index 7e4792bb9d..7b545e4634 100644
--- a/docs/cli/alias/ls.md
+++ b/docs/cli/tool-alias/ls.md
@@ -1,9 +1,9 @@
 <!-- @generated by usage-cli from usage spec -->
-# `mise alias ls`
+# `mise tool-alias ls`
 
-- **Usage**: `mise alias ls [--no-header] [TOOL]`
+- **Usage**: `mise tool-alias ls [--no-header] [TOOL]`
 - **Aliases**: `list`
-- **Source code**: [`src/cli/alias/ls.rs`](https://github.com/jdx/mise/blob/main/src/cli/alias/ls.rs)
+- **Source code**: [`src/cli/tool_alias/ls.rs`](https://github.com/jdx/mise/blob/main/src/cli/tool_alias/ls.rs)
 
 List aliases
 Shows the aliases that can be specified.
diff --git a/docs/cli/alias/set.md b/docs/cli/tool-alias/set.md
similarity index 70%
rename from docs/cli/alias/set.md
rename to docs/cli/tool-alias/set.md
index 5e35330e89..32f363ed37 100644
--- a/docs/cli/alias/set.md
+++ b/docs/cli/tool-alias/set.md
@@ -1,9 +1,9 @@
 <!-- @generated by usage-cli from usage spec -->
-# `mise alias set`
+# `mise tool-alias set`
 
-- **Usage**: `mise alias set <ARGS>…`
+- **Usage**: `mise tool-alias set <ARGS>…`
 - **Aliases**: `add`, `create`
-- **Source code**: [`src/cli/alias/set.rs`](https://github.com/jdx/mise/blob/main/src/cli/alias/set.rs)
+- **Source code**: [`src/cli/tool_alias/set.rs`](https://github.com/jdx/mise/blob/main/src/cli/tool_alias/set.rs)
 
 Add/update an alias for a backend/plugin
 
diff --git a/docs/cli/alias/unset.md b/docs/cli/tool-alias/unset.md
similarity index 65%
rename from docs/cli/alias/unset.md
rename to docs/cli/tool-alias/unset.md
index ea0b0ba0ad..515d16bf7f 100644
--- a/docs/cli/alias/unset.md
+++ b/docs/cli/tool-alias/unset.md
@@ -1,9 +1,9 @@
 <!-- @generated by usage-cli from usage spec -->
-# `mise alias unset`
+# `mise tool-alias unset`
 
-- **Usage**: `mise alias unset <PLUGIN> [ALIAS]`
+- **Usage**: `mise tool-alias unset <PLUGIN> [ALIAS]`
 - **Aliases**: `rm`, `remove`, `delete`, `del`
-- **Source code**: [`src/cli/alias/unset.rs`](https://github.com/jdx/mise/blob/main/src/cli/alias/unset.rs)
+- **Source code**: [`src/cli/tool_alias/unset.rs`](https://github.com/jdx/mise/blob/main/src/cli/tool_alias/unset.rs)
 
 Clears an alias for a backend/plugin
 
diff --git a/man/man1/mise.1 b/man/man1/mise.1
index ab9e11fd1b..bdd427d688 100644
--- a/man/man1/mise.1
+++ b/man/man1/mise.1
@@ -101,28 +101,25 @@ Task arguments
 \fBactivate\fR
 Initializes mise in the current shell session
 .TP
-\fBalias\fR
-Manage version aliases.
-.RS
-\fIAliases: \fRa
-.RE
+\fBtool\-alias\fR
+Manage tool version aliases.
 .TP
-\fBalias get\fR
+\fBtool\-alias get\fR
 Show an alias for a plugin
 .TP
-\fBalias ls\fR
+\fBtool\-alias ls\fR
 List aliases
 .RS
 \fIAliases: \fRlist
 .RE
 .TP
-\fBalias set\fR
+\fBtool\-alias set\fR
 Add/update an alias for a backend/plugin
 .RS
 \fIAliases: \fRadd, create
 .RE
 .TP
-\fBalias unset\fR
+\fBtool\-alias unset\fR
 Clears an alias for a backend/plugin
 .RS
 \fIAliases: \fRrm, remove, delete, del
@@ -546,10 +543,10 @@ Show "mise: <PLUGIN>@<VERSION>" message when changing directories
 .TP
 \fB<SHELL_TYPE>\fR
 Shell type to generate the script for
-.SH "MISE ALIAS"
-Manage version aliases.
+.SH "MISE TOOL-ALIAS"
+Manage tool version aliases.
 .PP
-\fBUsage:\fR mise alias [OPTIONS] [COMMAND]
+\fBUsage:\fR mise tool\-alias [OPTIONS] [COMMAND]
 .PP
 \fBOptions:\fR
 .PP
@@ -559,12 +556,12 @@ filter aliases by plugin
 .TP
 \fB\-\-no\-header\fR
 Don't show table header
-.SH "MISE ALIAS GET"
+.SH "MISE TOOL-ALIAS GET"
 Show an alias for a plugin
 
 This is the contents of an alias.<PLUGIN> entry in ~/.config/mise/config.toml
 .PP
-\fBUsage:\fR mise alias get <PLUGIN> <ALIAS>
+\fBUsage:\fR mise tool\-alias get <PLUGIN> <ALIAS>
 .PP
 \fBArguments:\fR
 .PP
@@ -574,7 +571,7 @@ The plugin to show the alias for
 .TP
 \fB<ALIAS>\fR
 The alias to show
-.SH "MISE ALIAS LS"
+.SH "MISE TOOL-ALIAS LS"
 List aliases
 Shows the aliases that can be specified.
 These can come from user config or from plugins in `bin/list\-aliases`.
@@ -584,7 +581,7 @@ For user config, aliases are defined like the following in `~/.config/mise/confi
     [alias.node.versions]
     lts = "22.0.0"
 .PP
-\fBUsage:\fR mise alias ls [OPTIONS] [<TOOL>]
+\fBUsage:\fR mise tool\-alias ls [OPTIONS] [<TOOL>]
 .PP
 \fBOptions:\fR
 .PP
@@ -596,12 +593,12 @@ Don't show table header
 .TP
 \fB<TOOL>\fR
 Show aliases for <TOOL>
-.SH "MISE ALIAS SET"
+.SH "MISE TOOL-ALIAS SET"
 Add/update an alias for a backend/plugin
 
 This modifies the contents of ~/.config/mise/config.toml
 .PP
-\fBUsage:\fR mise alias set <PLUGIN> <ALIAS> [<VALUE>]
+\fBUsage:\fR mise tool\-alias set <PLUGIN> <ALIAS> [<VALUE>]
 .PP
 \fBArguments:\fR
 .PP
@@ -614,12 +611,12 @@ The alias to set
 .TP
 \fB<VALUE>\fR
 The value to set the alias to
-.SH "MISE ALIAS UNSET"
+.SH "MISE TOOL-ALIAS UNSET"
 Clears an alias for a backend/plugin
 
 This modifies the contents of ~/.config/mise/config.toml
 .PP
-\fBUsage:\fR mise alias unset <PLUGIN> [<ALIAS>]
+\fBUsage:\fR mise tool\-alias unset <PLUGIN> [<ALIAS>]
 .PP
 \fBArguments:\fR
 .PP
diff --git a/mise.usage.kdl b/mise.usage.kdl
index b720fc53c9..a458a4bd6e 100644
--- a/mise.usage.kdl
+++ b/mise.usage.kdl
@@ -78,9 +78,8 @@ cmd activate help="Initializes mise in the current shell session" {
         choices bash elvish fish nu xonsh zsh pwsh
     }
 }
-cmd alias help="Manage version aliases." {
-    alias a
-    alias aliases hide=#true
+cmd tool-alias help="Manage tool version aliases." {
+    alias alias aliases hide=#true
     flag "-p --plugin" help="filter aliases by plugin" {
         arg <PLUGIN>
     }
diff --git a/xtasks/fig/src/mise.ts b/xtasks/fig/src/mise.ts
index 23b5018154..cbdd7ed027 100644
--- a/xtasks/fig/src/mise.ts
+++ b/xtasks/fig/src/mise.ts
@@ -538,8 +538,8 @@ const completionSpec: Fig.Spec = {
       },
     },
     {
-      name: ["alias", "a"],
-      description: "Manage version aliases.",
+      name: "tool-alias",
+      description: "Manage tool version aliases.",
       subcommands: [
         {
           name: "get",

From 9cfd8a04dc5ff8983028fa14947c6288d65d4a6f Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Wed, 17 Dec 2025 10:45:12 -0600
Subject: [PATCH 5/8] feat(cli): add shell-alias command and rename alias to
 tool-alias

- Rename alias directory/module to tool_alias
- Rename Alias* structs to ToolAlias*
- Add shell-alias command for managing shell aliases
- Add set_shell_alias/remove_shell_alias methods to MiseToml
- Update examples to use new command names
---
 src/cli/mod.rs                         |  7 +++-
 src/cli/shell_alias/get.rs             | 32 ++++++++++++++++
 src/cli/shell_alias/ls.rs              | 51 ++++++++++++++++++++++++++
 src/cli/shell_alias/mod.rs             | 47 ++++++++++++++++++++++++
 src/cli/shell_alias/set.rs             | 32 ++++++++++++++++
 src/cli/shell_alias/unset.rs           | 29 +++++++++++++++
 src/cli/{alias => tool_alias}/get.rs   |  8 ++--
 src/cli/{alias => tool_alias}/ls.rs    | 10 ++---
 src/cli/{alias => tool_alias}/mod.rs   | 14 +++----
 src/cli/{alias => tool_alias}/set.rs   |  8 ++--
 src/cli/{alias => tool_alias}/unset.rs |  8 ++--
 src/config/config_file/mise_toml.rs    | 26 +++++++++++++
 12 files changed, 246 insertions(+), 26 deletions(-)
 create mode 100644 src/cli/shell_alias/get.rs
 create mode 100644 src/cli/shell_alias/ls.rs
 create mode 100644 src/cli/shell_alias/mod.rs
 create mode 100644 src/cli/shell_alias/set.rs
 create mode 100644 src/cli/shell_alias/unset.rs
 rename src/cli/{alias => tool_alias}/get.rs (83%)
 rename src/cli/{alias => tool_alias}/ls.rs (92%)
 rename src/cli/{alias => tool_alias}/mod.rs (81%)
 rename src/cli/{alias => tool_alias}/set.rs (85%)
 rename src/cli/{alias => tool_alias}/unset.rs (87%)

diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 3fc5a50041..2121acbcad 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -10,7 +10,6 @@ use eyre::bail;
 use std::path::PathBuf;
 
 mod activate;
-mod alias;
 pub mod args;
 mod asdf;
 pub mod backends;
@@ -31,6 +30,7 @@ mod generate;
 mod global;
 mod hook_env;
 mod hook_not_found;
+mod tool_alias;
 
 pub use hook_env::HookReason;
 mod implode;
@@ -58,6 +58,7 @@ pub mod self_update;
 mod set;
 mod settings;
 mod shell;
+mod shell_alias;
 mod sync;
 mod tasks;
 mod test_tool;
@@ -191,7 +192,7 @@ pub struct Cli {
 #[strum(serialize_all = "kebab-case")]
 pub enum Commands {
     Activate(activate::Activate),
-    ToolAlias(Box<alias::Alias>),
+    ToolAlias(Box<tool_alias::ToolAlias>),
     Asdf(asdf::Asdf),
     Backends(backends::Backends),
     BinPaths(bin_paths::BinPaths),
@@ -235,6 +236,7 @@ pub enum Commands {
     Set(set::Set),
     Settings(settings::Settings),
     Shell(shell::Shell),
+    ShellAlias(shell_alias::ShellAlias),
     Sync(sync::Sync),
     Tasks(tasks::Tasks),
     TestTool(test_tool::TestTool),
@@ -301,6 +303,7 @@ impl Commands {
             Self::Set(cmd) => cmd.run().await,
             Self::Settings(cmd) => cmd.run().await,
             Self::Shell(cmd) => cmd.run().await,
+            Self::ShellAlias(cmd) => cmd.run().await,
             Self::Sync(cmd) => cmd.run().await,
             Self::Tasks(cmd) => cmd.run().await,
             Self::TestTool(cmd) => cmd.run().await,
diff --git a/src/cli/shell_alias/get.rs b/src/cli/shell_alias/get.rs
new file mode 100644
index 0000000000..a5e3d07080
--- /dev/null
+++ b/src/cli/shell_alias/get.rs
@@ -0,0 +1,32 @@
+use color_eyre::eyre::{Result, eyre};
+
+use crate::config::Config;
+
+/// Show the command for a shell alias
+#[derive(Debug, clap::Args)]
+#[clap(after_long_help = AFTER_LONG_HELP, verbatim_doc_comment)]
+pub struct ShellAliasGet {
+    /// The alias to show
+    pub alias: String,
+}
+
+impl ShellAliasGet {
+    pub async fn run(self) -> Result<()> {
+        let config = Config::get().await?;
+        match config.shell_aliases.get(&self.alias) {
+            Some((command, _path)) => {
+                miseprintln!("{command}");
+                Ok(())
+            }
+            None => Err(eyre!("Unknown shell alias: {}", &self.alias)),
+        }
+    }
+}
+
+static AFTER_LONG_HELP: &str = color_print::cstr!(
+    r#"<bold><underline>Examples:</underline></bold>
+
+    $ <bold>mise shell-alias get ll</bold>
+    ls -la
+"#
+);
diff --git a/src/cli/shell_alias/ls.rs b/src/cli/shell_alias/ls.rs
new file mode 100644
index 0000000000..5a273cc560
--- /dev/null
+++ b/src/cli/shell_alias/ls.rs
@@ -0,0 +1,51 @@
+use eyre::Result;
+use tabled::Tabled;
+
+use crate::config::Config;
+use crate::ui::table;
+
+/// List shell aliases
+///
+/// Shows the shell aliases that are set in the current directory.
+/// These are defined in `mise.toml` under the `[shell_alias]` section.
+#[derive(Debug, clap::Args)]
+#[clap(visible_alias = "list", after_long_help = AFTER_LONG_HELP, verbatim_doc_comment)]
+pub struct ShellAliasLs {
+    /// Don't show table header
+    #[clap(long)]
+    pub no_header: bool,
+}
+
+impl ShellAliasLs {
+    pub async fn run(self) -> Result<()> {
+        let config = Config::get().await?;
+        let rows = config
+            .shell_aliases
+            .iter()
+            .map(|(name, (command, _path))| Row {
+                alias: name.clone(),
+                command: command.clone(),
+            })
+            .collect::<Vec<_>>();
+        let mut table = tabled::Table::new(rows);
+        table::default_style(&mut table, self.no_header);
+        miseprintln!("{table}");
+        Ok(())
+    }
+}
+
+#[derive(Tabled)]
+struct Row {
+    alias: String,
+    command: String,
+}
+
+static AFTER_LONG_HELP: &str = color_print::cstr!(
+    r#"<bold><underline>Examples:</underline></bold>
+
+    $ <bold>mise shell-alias ls</bold>
+    alias    command
+    ll       ls -la
+    gs       git status
+"#
+);
diff --git a/src/cli/shell_alias/mod.rs b/src/cli/shell_alias/mod.rs
new file mode 100644
index 0000000000..91fdd412a6
--- /dev/null
+++ b/src/cli/shell_alias/mod.rs
@@ -0,0 +1,47 @@
+use clap::Subcommand;
+use eyre::Result;
+
+mod get;
+mod ls;
+mod set;
+mod unset;
+
+#[derive(Debug, clap::Args)]
+#[clap(name = "shell-alias", about = "Manage shell aliases.")]
+pub struct ShellAlias {
+    #[clap(subcommand)]
+    command: Option<Commands>,
+
+    /// Don't show table header
+    #[clap(long)]
+    pub no_header: bool,
+}
+
+#[derive(Debug, Subcommand)]
+enum Commands {
+    Get(get::ShellAliasGet),
+    Ls(ls::ShellAliasLs),
+    Set(set::ShellAliasSet),
+    Unset(unset::ShellAliasUnset),
+}
+
+impl Commands {
+    pub async fn run(self) -> Result<()> {
+        match self {
+            Self::Get(cmd) => cmd.run().await,
+            Self::Ls(cmd) => cmd.run().await,
+            Self::Set(cmd) => cmd.run().await,
+            Self::Unset(cmd) => cmd.run().await,
+        }
+    }
+}
+
+impl ShellAlias {
+    pub async fn run(self) -> Result<()> {
+        let cmd = self.command.unwrap_or(Commands::Ls(ls::ShellAliasLs {
+            no_header: self.no_header,
+        }));
+
+        cmd.run().await
+    }
+}
diff --git a/src/cli/shell_alias/set.rs b/src/cli/shell_alias/set.rs
new file mode 100644
index 0000000000..9dee4caf7e
--- /dev/null
+++ b/src/cli/shell_alias/set.rs
@@ -0,0 +1,32 @@
+use eyre::Result;
+
+use crate::config::Config;
+use crate::config::config_file::ConfigFile;
+
+/// Add/update a shell alias
+///
+/// This modifies the contents of ~/.config/mise/config.toml
+#[derive(Debug, clap::Args)]
+#[clap(visible_aliases = ["add", "create"], after_long_help = AFTER_LONG_HELP, verbatim_doc_comment)]
+pub struct ShellAliasSet {
+    /// The alias name
+    pub alias: String,
+    /// The command to run
+    pub command: String,
+}
+
+impl ShellAliasSet {
+    pub async fn run(self) -> Result<()> {
+        let mut global_config = Config::get().await?.global_config()?;
+        global_config.set_shell_alias(&self.alias, &self.command)?;
+        global_config.save()
+    }
+}
+
+static AFTER_LONG_HELP: &str = color_print::cstr!(
+    r#"<bold><underline>Examples:</underline></bold>
+
+    $ <bold>mise shell-alias set ll "ls -la"</bold>
+    $ <bold>mise shell-alias set gs "git status"</bold>
+"#
+);
diff --git a/src/cli/shell_alias/unset.rs b/src/cli/shell_alias/unset.rs
new file mode 100644
index 0000000000..74ad09b029
--- /dev/null
+++ b/src/cli/shell_alias/unset.rs
@@ -0,0 +1,29 @@
+use eyre::Result;
+
+use crate::config::Config;
+use crate::config::config_file::ConfigFile;
+
+/// Removes a shell alias
+///
+/// This modifies the contents of ~/.config/mise/config.toml
+#[derive(Debug, clap::Args)]
+#[clap(visible_aliases = ["rm", "remove", "delete", "del"], after_long_help = AFTER_LONG_HELP, verbatim_doc_comment)]
+pub struct ShellAliasUnset {
+    /// The alias to remove
+    pub alias: String,
+}
+
+impl ShellAliasUnset {
+    pub async fn run(self) -> Result<()> {
+        let mut global_config = Config::get().await?.global_config()?;
+        global_config.remove_shell_alias(&self.alias)?;
+        global_config.save()
+    }
+}
+
+static AFTER_LONG_HELP: &str = color_print::cstr!(
+    r#"<bold><underline>Examples:</underline></bold>
+
+    $ <bold>mise shell-alias unset ll</bold>
+"#
+);
diff --git a/src/cli/alias/get.rs b/src/cli/tool_alias/get.rs
similarity index 83%
rename from src/cli/alias/get.rs
rename to src/cli/tool_alias/get.rs
index 4cb0598c3a..eed9ebc8bd 100644
--- a/src/cli/alias/get.rs
+++ b/src/cli/tool_alias/get.rs
@@ -5,18 +5,18 @@ use crate::config::Config;
 
 /// Show an alias for a plugin
 ///
-/// This is the contents of an alias.<PLUGIN> entry in ~/.config/mise/config.toml
+/// This is the contents of a tool_alias.<PLUGIN> entry in ~/.config/mise/config.toml
 ///
 #[derive(Debug, clap::Args)]
 #[clap(after_long_help = AFTER_LONG_HELP, verbatim_doc_comment)]
-pub struct AliasGet {
+pub struct ToolAliasGet {
     /// The plugin to show the alias for
     pub plugin: BackendArg,
     /// The alias to show
     pub alias: String,
 }
 
-impl AliasGet {
+impl ToolAliasGet {
     pub async fn run(self) -> Result<()> {
         let config = Config::get().await?;
         match config.all_aliases.get(&self.plugin.short) {
@@ -35,7 +35,7 @@ impl AliasGet {
 static AFTER_LONG_HELP: &str = color_print::cstr!(
     r#"<bold><underline>Examples:</underline></bold>
 
-    $ <bold>mise alias get node lts-hydrogen</bold>
+    $ <bold>mise tool-alias get node lts-hydrogen</bold>
     20.0.0
 "#
 );
diff --git a/src/cli/alias/ls.rs b/src/cli/tool_alias/ls.rs
similarity index 92%
rename from src/cli/alias/ls.rs
rename to src/cli/tool_alias/ls.rs
index 31de9335dd..4be840d5ae 100644
--- a/src/cli/alias/ls.rs
+++ b/src/cli/tool_alias/ls.rs
@@ -6,17 +6,17 @@ use crate::cli::args::BackendArg;
 use crate::config::Config;
 use crate::ui::table;
 
-/// List aliases
+/// List tool version aliases
 /// Shows the aliases that can be specified.
 /// These can come from user config or from plugins in `bin/list-aliases`.
 ///
 /// For user config, aliases are defined like the following in `~/.config/mise/config.toml`:
 ///
-///     [alias.node.versions]
+///     [tool_alias.node.versions]
 ///     lts = "22.0.0"
 #[derive(Debug, clap::Args)]
 #[clap(visible_alias = "list", after_long_help = AFTER_LONG_HELP, verbatim_doc_comment)]
-pub struct AliasLs {
+pub struct ToolAliasLs {
     /// Show aliases for <TOOL>
     #[clap()]
     pub tool: Option<BackendArg>,
@@ -26,7 +26,7 @@ pub struct AliasLs {
     pub no_header: bool,
 }
 
-impl AliasLs {
+impl ToolAliasLs {
     pub async fn run(self) -> Result<()> {
         let config = Config::get().await?;
         let rows = config
@@ -66,7 +66,7 @@ struct Row {
 static AFTER_LONG_HELP: &str = color_print::cstr!(
     r#"<bold><underline>Examples:</underline></bold>
 
-    $ <bold>mise aliases</bold>
+    $ <bold>mise tool-alias ls</bold>
     node  lts-jod      22
 "#
 );
diff --git a/src/cli/alias/mod.rs b/src/cli/tool_alias/mod.rs
similarity index 81%
rename from src/cli/alias/mod.rs
rename to src/cli/tool_alias/mod.rs
index e3809d2d8e..b7575e725a 100644
--- a/src/cli/alias/mod.rs
+++ b/src/cli/tool_alias/mod.rs
@@ -15,7 +15,7 @@ mod unset;
     alias = "alias",
     alias = "aliases"
 )]
-pub struct Alias {
+pub struct ToolAlias {
     #[clap(subcommand)]
     command: Option<Commands>,
 
@@ -30,10 +30,10 @@ pub struct Alias {
 
 #[derive(Debug, Subcommand)]
 enum Commands {
-    Get(get::AliasGet),
-    Ls(ls::AliasLs),
-    Set(set::AliasSet),
-    Unset(unset::AliasUnset),
+    Get(get::ToolAliasGet),
+    Ls(ls::ToolAliasLs),
+    Set(set::ToolAliasSet),
+    Unset(unset::ToolAliasUnset),
 }
 
 impl Commands {
@@ -47,9 +47,9 @@ impl Commands {
     }
 }
 
-impl Alias {
+impl ToolAlias {
     pub async fn run(self) -> Result<()> {
-        let cmd = self.command.unwrap_or(Commands::Ls(ls::AliasLs {
+        let cmd = self.command.unwrap_or(Commands::Ls(ls::ToolAliasLs {
             tool: self.plugin,
             no_header: self.no_header,
         }));
diff --git a/src/cli/alias/set.rs b/src/cli/tool_alias/set.rs
similarity index 85%
rename from src/cli/alias/set.rs
rename to src/cli/tool_alias/set.rs
index 6f57caae9f..bc1da1eb7b 100644
--- a/src/cli/alias/set.rs
+++ b/src/cli/tool_alias/set.rs
@@ -9,7 +9,7 @@ use crate::config::config_file::ConfigFile;
 /// This modifies the contents of ~/.config/mise/config.toml
 #[derive(Debug, clap::Args)]
 #[clap(visible_aliases = ["add", "create"], after_long_help = AFTER_LONG_HELP, verbatim_doc_comment)]
-pub struct AliasSet {
+pub struct ToolAliasSet {
     /// The backend/plugin to set the alias for
     pub plugin: BackendArg,
     /// The alias to set
@@ -18,7 +18,7 @@ pub struct AliasSet {
     pub value: Option<String>,
 }
 
-impl AliasSet {
+impl ToolAliasSet {
     pub async fn run(self) -> Result<()> {
         let mut global_config = Config::get().await?.global_config()?;
         match &self.value {
@@ -32,7 +32,7 @@ impl AliasSet {
 static AFTER_LONG_HELP: &str = color_print::cstr!(
     r#"<bold><underline>Examples:</underline></bold>
 
-    $ <bold>mise alias set maven asdf:mise-plugins/mise-maven</bold>
-    $ <bold>mise alias set node lts-jod 22.0.0</bold>
+    $ <bold>mise tool-alias set maven asdf:mise-plugins/mise-maven</bold>
+    $ <bold>mise tool-alias set node lts-jod 22.0.0</bold>
 "#
 );
diff --git a/src/cli/alias/unset.rs b/src/cli/tool_alias/unset.rs
similarity index 87%
rename from src/cli/alias/unset.rs
rename to src/cli/tool_alias/unset.rs
index b4c2b4ab5f..0cd533cb31 100644
--- a/src/cli/alias/unset.rs
+++ b/src/cli/tool_alias/unset.rs
@@ -9,14 +9,14 @@ use crate::config::config_file::ConfigFile;
 /// This modifies the contents of ~/.config/mise/config.toml
 #[derive(Debug, clap::Args)]
 #[clap(visible_aliases = ["rm", "remove", "delete", "del"], after_long_help = AFTER_LONG_HELP, verbatim_doc_comment)]
-pub struct AliasUnset {
+pub struct ToolAliasUnset {
     /// The backend/plugin to remove the alias from
     pub plugin: BackendArg,
     /// The alias to remove
     pub alias: Option<String>,
 }
 
-impl AliasUnset {
+impl ToolAliasUnset {
     pub async fn run(self) -> Result<()> {
         let mut global_config = Config::get().await?.global_config()?;
         match self.alias {
@@ -34,7 +34,7 @@ impl AliasUnset {
 static AFTER_LONG_HELP: &str = color_print::cstr!(
     r#"<bold><underline>Examples:</underline></bold>
 
-    $ <bold>mise alias unset maven</bold>
-    $ <bold>mise alias unset node lts-jod</bold>
+    $ <bold>mise tool-alias unset maven</bold>
+    $ <bold>mise tool-alias unset node lts-jod</bold>
 "#
 );
diff --git a/src/config/config_file/mise_toml.rs b/src/config/config_file/mise_toml.rs
index 6764c2d028..a4a76a27db 100644
--- a/src/config/config_file/mise_toml.rs
+++ b/src/config/config_file/mise_toml.rs
@@ -295,6 +295,32 @@ impl MiseToml {
         Ok(())
     }
 
+    pub fn set_shell_alias(&mut self, name: &str, command: &str) -> eyre::Result<()> {
+        self.shell_alias.insert(name.into(), command.into());
+        self.doc_mut()?
+            .get_mut()
+            .unwrap()
+            .entry("shell_alias")
+            .or_insert_with(table)
+            .as_table_like_mut()
+            .unwrap()
+            .insert(name, value(command));
+        Ok(())
+    }
+
+    pub fn remove_shell_alias(&mut self, name: &str) -> eyre::Result<()> {
+        self.shell_alias.shift_remove(name);
+        let mut doc = self.doc_mut()?;
+        let doc = doc.get_mut().unwrap();
+        if let Some(shell_alias) = doc.get_mut("shell_alias").and_then(|v| v.as_table_mut()) {
+            shell_alias.remove(name);
+            if shell_alias.is_empty() {
+                doc.as_table_mut().remove("shell_alias");
+            }
+        }
+        Ok(())
+    }
+
     pub fn update_env<V: Into<Value>>(&mut self, key: &str, value: V) -> eyre::Result<()> {
         let mut doc = self.doc_mut()?;
         let mut env_tbl = doc

From 8af38caaa6468094ccd1892e0ea7009dc1a4c659 Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Wed, 17 Dec 2025 16:54:16 +0000
Subject: [PATCH 6/8] [autofix.ci] apply automated fixes

---
 docs/.vitepress/cli_commands.ts | 17 ++++++
 docs/cli/index.md               |  5 ++
 docs/cli/shell-alias.md         | 20 +++++++
 docs/cli/shell-alias/get.md     | 20 +++++++
 docs/cli/shell-alias/ls.md      | 26 ++++++++++
 docs/cli/shell-alias/set.md     | 27 ++++++++++
 docs/cli/shell-alias/unset.md   | 22 ++++++++
 docs/cli/tool-alias/get.md      |  4 +-
 docs/cli/tool-alias/ls.md       |  6 +--
 docs/cli/tool-alias/set.md      |  4 +-
 docs/cli/tool-alias/unset.md    |  4 +-
 man/man1/mise.1                 | 92 +++++++++++++++++++++++++++++++--
 mise.usage.kdl                  | 40 +++++++++++---
 xtasks/fig/src/mise.ts          | 62 +++++++++++++++++++++-
 14 files changed, 328 insertions(+), 21 deletions(-)
 create mode 100644 docs/cli/shell-alias.md
 create mode 100644 docs/cli/shell-alias/get.md
 create mode 100644 docs/cli/shell-alias/ls.md
 create mode 100644 docs/cli/shell-alias/set.md
 create mode 100644 docs/cli/shell-alias/unset.md

diff --git a/docs/.vitepress/cli_commands.ts b/docs/.vitepress/cli_commands.ts
index 281770d17f..3197626ecc 100644
--- a/docs/.vitepress/cli_commands.ts
+++ b/docs/.vitepress/cli_commands.ts
@@ -243,6 +243,23 @@ export const commands: { [key: string]: Command } = {
   shell: {
     hide: false,
   },
+  "shell-alias": {
+    hide: false,
+    subcommands: {
+      get: {
+        hide: false,
+      },
+      ls: {
+        hide: false,
+      },
+      set: {
+        hide: false,
+      },
+      unset: {
+        hide: false,
+      },
+    },
+  },
   sync: {
     hide: false,
     subcommands: {
diff --git a/docs/cli/index.md b/docs/cli/index.md
index 94ea805766..d067b07e17 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -134,6 +134,11 @@ Can also use `MISE_NO_CONFIG=1`
 - [`mise settings set [-l --local] <SETTING> <VALUE>`](/cli/settings/set.md)
 - [`mise settings unset [-l --local] <KEY>`](/cli/settings/unset.md)
 - [`mise shell [FLAGS] <TOOL@VERSION>…`](/cli/shell.md)
+- [`mise shell-alias [--no-header] <SUBCOMMAND>`](/cli/shell-alias.md)
+- [`mise shell-alias get <ALIAS>`](/cli/shell-alias/get.md)
+- [`mise shell-alias ls [--no-header]`](/cli/shell-alias/ls.md)
+- [`mise shell-alias set <ALIAS> <COMMAND>`](/cli/shell-alias/set.md)
+- [`mise shell-alias unset <ALIAS>`](/cli/shell-alias/unset.md)
 - [`mise sync <SUBCOMMAND>`](/cli/sync.md)
 - [`mise sync node [FLAGS]`](/cli/sync/node.md)
 - [`mise sync python [--pyenv] [--uv]`](/cli/sync/python.md)
diff --git a/docs/cli/shell-alias.md b/docs/cli/shell-alias.md
new file mode 100644
index 0000000000..0136607b4d
--- /dev/null
+++ b/docs/cli/shell-alias.md
@@ -0,0 +1,20 @@
+<!-- @generated by usage-cli from usage spec -->
+# `mise shell-alias`
+
+- **Usage**: `mise shell-alias [--no-header] <SUBCOMMAND>`
+- **Source code**: [`src/cli/shell_alias/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/shell_alias/mod.rs)
+
+Manage shell aliases.
+
+## Flags
+
+### `--no-header`
+
+Don't show table header
+
+## Subcommands
+
+- [`mise shell-alias get <ALIAS>`](/cli/shell-alias/get.md)
+- [`mise shell-alias ls [--no-header]`](/cli/shell-alias/ls.md)
+- [`mise shell-alias set <ALIAS> <COMMAND>`](/cli/shell-alias/set.md)
+- [`mise shell-alias unset <ALIAS>`](/cli/shell-alias/unset.md)
diff --git a/docs/cli/shell-alias/get.md b/docs/cli/shell-alias/get.md
new file mode 100644
index 0000000000..9d6c0f24f2
--- /dev/null
+++ b/docs/cli/shell-alias/get.md
@@ -0,0 +1,20 @@
+<!-- @generated by usage-cli from usage spec -->
+# `mise shell-alias get`
+
+- **Usage**: `mise shell-alias get <ALIAS>`
+- **Source code**: [`src/cli/shell_alias/get.rs`](https://github.com/jdx/mise/blob/main/src/cli/shell_alias/get.rs)
+
+Show the command for a shell alias
+
+## Arguments
+
+### `<ALIAS>`
+
+The alias to show
+
+Examples:
+
+```
+$ mise shell-alias get ll
+ls -la
+```
diff --git a/docs/cli/shell-alias/ls.md b/docs/cli/shell-alias/ls.md
new file mode 100644
index 0000000000..1ba6309968
--- /dev/null
+++ b/docs/cli/shell-alias/ls.md
@@ -0,0 +1,26 @@
+<!-- @generated by usage-cli from usage spec -->
+# `mise shell-alias ls`
+
+- **Usage**: `mise shell-alias ls [--no-header]`
+- **Aliases**: `list`
+- **Source code**: [`src/cli/shell_alias/ls.rs`](https://github.com/jdx/mise/blob/main/src/cli/shell_alias/ls.rs)
+
+List shell aliases
+
+Shows the shell aliases that are set in the current directory.
+These are defined in `mise.toml` under the `[shell_alias]` section.
+
+## Flags
+
+### `--no-header`
+
+Don't show table header
+
+Examples:
+
+```
+$ mise shell-alias ls
+alias    command
+ll       ls -la
+gs       git status
+```
diff --git a/docs/cli/shell-alias/set.md b/docs/cli/shell-alias/set.md
new file mode 100644
index 0000000000..1c7479b01e
--- /dev/null
+++ b/docs/cli/shell-alias/set.md
@@ -0,0 +1,27 @@
+<!-- @generated by usage-cli from usage spec -->
+# `mise shell-alias set`
+
+- **Usage**: `mise shell-alias set <ALIAS> <COMMAND>`
+- **Aliases**: `add`, `create`
+- **Source code**: [`src/cli/shell_alias/set.rs`](https://github.com/jdx/mise/blob/main/src/cli/shell_alias/set.rs)
+
+Add/update a shell alias
+
+This modifies the contents of ~/.config/mise/config.toml
+
+## Arguments
+
+### `<ALIAS>`
+
+The alias name
+
+### `<COMMAND>`
+
+The command to run
+
+Examples:
+
+```
+mise shell-alias set ll "ls -la"
+mise shell-alias set gs "git status"
+```
diff --git a/docs/cli/shell-alias/unset.md b/docs/cli/shell-alias/unset.md
new file mode 100644
index 0000000000..2712129634
--- /dev/null
+++ b/docs/cli/shell-alias/unset.md
@@ -0,0 +1,22 @@
+<!-- @generated by usage-cli from usage spec -->
+# `mise shell-alias unset`
+
+- **Usage**: `mise shell-alias unset <ALIAS>`
+- **Aliases**: `rm`, `remove`, `delete`, `del`
+- **Source code**: [`src/cli/shell_alias/unset.rs`](https://github.com/jdx/mise/blob/main/src/cli/shell_alias/unset.rs)
+
+Removes a shell alias
+
+This modifies the contents of ~/.config/mise/config.toml
+
+## Arguments
+
+### `<ALIAS>`
+
+The alias to remove
+
+Examples:
+
+```
+mise shell-alias unset ll
+```
diff --git a/docs/cli/tool-alias/get.md b/docs/cli/tool-alias/get.md
index b4fab982f3..f3bafb6bab 100644
--- a/docs/cli/tool-alias/get.md
+++ b/docs/cli/tool-alias/get.md
@@ -6,7 +6,7 @@
 
 Show an alias for a plugin
 
-This is the contents of an alias.&lt;PLUGIN> entry in ~/.config/mise/config.toml
+This is the contents of a tool_alias.&lt;PLUGIN> entry in ~/.config/mise/config.toml
 
 ## Arguments
 
@@ -21,6 +21,6 @@ The alias to show
 Examples:
 
 ```
-$ mise alias get node lts-hydrogen
+$ mise tool-alias get node lts-hydrogen
 20.0.0
 ```
diff --git a/docs/cli/tool-alias/ls.md b/docs/cli/tool-alias/ls.md
index 7b545e4634..4de565a282 100644
--- a/docs/cli/tool-alias/ls.md
+++ b/docs/cli/tool-alias/ls.md
@@ -5,14 +5,14 @@
 - **Aliases**: `list`
 - **Source code**: [`src/cli/tool_alias/ls.rs`](https://github.com/jdx/mise/blob/main/src/cli/tool_alias/ls.rs)
 
-List aliases
+List tool version aliases
 Shows the aliases that can be specified.
 These can come from user config or from plugins in `bin/list-aliases`.
 
 For user config, aliases are defined like the following in `~/.config/mise/config.toml`:
 
 ```
-[alias.node.versions]
+[tool_alias.node.versions]
 lts = "22.0.0"
 ```
 
@@ -31,6 +31,6 @@ Don't show table header
 Examples:
 
 ```
-$ mise aliases
+$ mise tool-alias ls
 node  lts-jod      22
 ```
diff --git a/docs/cli/tool-alias/set.md b/docs/cli/tool-alias/set.md
index 32f363ed37..cb3c489a4b 100644
--- a/docs/cli/tool-alias/set.md
+++ b/docs/cli/tool-alias/set.md
@@ -26,6 +26,6 @@ The value to set the alias to
 Examples:
 
 ```
-mise alias set maven asdf:mise-plugins/mise-maven
-mise alias set node lts-jod 22.0.0
+mise tool-alias set maven asdf:mise-plugins/mise-maven
+mise tool-alias set node lts-jod 22.0.0
 ```
diff --git a/docs/cli/tool-alias/unset.md b/docs/cli/tool-alias/unset.md
index 515d16bf7f..e3cd15fd6f 100644
--- a/docs/cli/tool-alias/unset.md
+++ b/docs/cli/tool-alias/unset.md
@@ -22,6 +22,6 @@ The alias to remove
 Examples:
 
 ```
-mise alias unset maven
-mise alias unset node lts-jod
+mise tool-alias unset maven
+mise tool-alias unset node lts-jod
 ```
diff --git a/man/man1/mise.1 b/man/man1/mise.1
index bdd427d688..915aa9f360 100644
--- a/man/man1/mise.1
+++ b/man/man1/mise.1
@@ -108,7 +108,7 @@ Manage tool version aliases.
 Show an alias for a plugin
 .TP
 \fBtool\-alias ls\fR
-List aliases
+List tool version aliases
 .RS
 \fIAliases: \fRlist
 .RE
@@ -398,6 +398,30 @@ Sets a tool version for the current session.
 \fIAliases: \fRsh
 .RE
 .TP
+\fBshell\-alias\fR
+Manage shell aliases.
+.TP
+\fBshell\-alias get\fR
+Show the command for a shell alias
+.TP
+\fBshell\-alias ls\fR
+List shell aliases
+.RS
+\fIAliases: \fRlist
+.RE
+.TP
+\fBshell\-alias set\fR
+Add/update a shell alias
+.RS
+\fIAliases: \fRadd, create
+.RE
+.TP
+\fBshell\-alias unset\fR
+Removes a shell alias
+.RS
+\fIAliases: \fRrm, remove, delete, del
+.RE
+.TP
 \fBsync\fR
 Synchronize tools from other version managers with mise
 .TP
@@ -559,7 +583,7 @@ Don't show table header
 .SH "MISE TOOL-ALIAS GET"
 Show an alias for a plugin
 
-This is the contents of an alias.<PLUGIN> entry in ~/.config/mise/config.toml
+This is the contents of a tool_alias.<PLUGIN> entry in ~/.config/mise/config.toml
 .PP
 \fBUsage:\fR mise tool\-alias get <PLUGIN> <ALIAS>
 .PP
@@ -572,13 +596,13 @@ The plugin to show the alias for
 \fB<ALIAS>\fR
 The alias to show
 .SH "MISE TOOL-ALIAS LS"
-List aliases
+List tool version aliases
 Shows the aliases that can be specified.
 These can come from user config or from plugins in `bin/list\-aliases`.
 
 For user config, aliases are defined like the following in `~/.config/mise/config.toml`:
 
-    [alias.node.versions]
+    [tool_alias.node.versions]
     lts = "22.0.0"
 .PP
 \fBUsage:\fR mise tool\-alias ls [OPTIONS] [<TOOL>]
@@ -2109,6 +2133,66 @@ Directly pipe stdin/stdout/stderr from plugin to user Sets \-\-jobs=1
 .TP
 \fB<TOOL@VERSION>\fR
 Tool(s) to use
+.SH "MISE SHELL-ALIAS"
+Manage shell aliases.
+.PP
+\fBUsage:\fR mise shell\-alias [OPTIONS] [COMMAND]
+.PP
+\fBOptions:\fR
+.PP
+.TP
+\fB\-\-no\-header\fR
+Don't show table header
+.SH "MISE SHELL-ALIAS GET"
+Show the command for a shell alias
+.PP
+\fBUsage:\fR mise shell\-alias get <ALIAS>
+.PP
+\fBArguments:\fR
+.PP
+.TP
+\fB<ALIAS>\fR
+The alias to show
+.SH "MISE SHELL-ALIAS LS"
+List shell aliases
+
+Shows the shell aliases that are set in the current directory.
+These are defined in `mise.toml` under the `[shell_alias]` section.
+.PP
+\fBUsage:\fR mise shell\-alias ls [OPTIONS]
+.PP
+\fBOptions:\fR
+.PP
+.TP
+\fB\-\-no\-header\fR
+Don't show table header
+.SH "MISE SHELL-ALIAS SET"
+Add/update a shell alias
+
+This modifies the contents of ~/.config/mise/config.toml
+.PP
+\fBUsage:\fR mise shell\-alias set <ALIAS> <COMMAND>
+.PP
+\fBArguments:\fR
+.PP
+.TP
+\fB<ALIAS>\fR
+The alias name
+.TP
+\fB<COMMAND>\fR
+The command to run
+.SH "MISE SHELL-ALIAS UNSET"
+Removes a shell alias
+
+This modifies the contents of ~/.config/mise/config.toml
+.PP
+\fBUsage:\fR mise shell\-alias unset <ALIAS>
+.PP
+\fBArguments:\fR
+.PP
+.TP
+\fB<ALIAS>\fR
+The alias to remove
 .SH "MISE SYNC NODE"
 Symlinks all tool versions from an external tool into mise
 
diff --git a/mise.usage.kdl b/mise.usage.kdl
index a458a4bd6e..16951db8a7 100644
--- a/mise.usage.kdl
+++ b/mise.usage.kdl
@@ -85,22 +85,22 @@ cmd tool-alias help="Manage tool version aliases." {
     }
     flag --no-header help="Don't show table header"
     cmd get help="Show an alias for a plugin" {
-        long_help "Show an alias for a plugin\n\nThis is the contents of an alias.<PLUGIN> entry in ~/.config/mise/config.toml"
-        after_long_help "Examples:\n\n    $ mise alias get node lts-hydrogen\n    20.0.0\n"
+        long_help "Show an alias for a plugin\n\nThis is the contents of a tool_alias.<PLUGIN> entry in ~/.config/mise/config.toml"
+        after_long_help "Examples:\n\n    $ mise tool-alias get node lts-hydrogen\n    20.0.0\n"
         arg <PLUGIN> help="The plugin to show the alias for"
         arg <ALIAS> help="The alias to show"
     }
-    cmd ls help="List aliases\nShows the aliases that can be specified.\nThese can come from user config or from plugins in `bin/list-aliases`." {
+    cmd ls help="List tool version aliases\nShows the aliases that can be specified.\nThese can come from user config or from plugins in `bin/list-aliases`." {
         alias list
-        long_help "List aliases\nShows the aliases that can be specified.\nThese can come from user config or from plugins in `bin/list-aliases`.\n\nFor user config, aliases are defined like the following in `~/.config/mise/config.toml`:\n\n    [alias.node.versions]\n    lts = \"22.0.0\""
-        after_long_help "Examples:\n\n    $ mise aliases\n    node  lts-jod      22\n"
+        long_help "List tool version aliases\nShows the aliases that can be specified.\nThese can come from user config or from plugins in `bin/list-aliases`.\n\nFor user config, aliases are defined like the following in `~/.config/mise/config.toml`:\n\n    [tool_alias.node.versions]\n    lts = \"22.0.0\""
+        after_long_help "Examples:\n\n    $ mise tool-alias ls\n    node  lts-jod      22\n"
         flag --no-header help="Don't show table header"
         arg "[TOOL]" help="Show aliases for <TOOL>" required=#false
     }
     cmd set help="Add/update an alias for a backend/plugin" {
         alias add create
         long_help "Add/update an alias for a backend/plugin\n\nThis modifies the contents of ~/.config/mise/config.toml"
-        after_long_help "Examples:\n\n    $ mise alias set maven asdf:mise-plugins/mise-maven\n    $ mise alias set node lts-jod 22.0.0\n"
+        after_long_help "Examples:\n\n    $ mise tool-alias set maven asdf:mise-plugins/mise-maven\n    $ mise tool-alias set node lts-jod 22.0.0\n"
         arg <PLUGIN> help="The backend/plugin to set the alias for"
         arg <ALIAS> help="The alias to set"
         arg "[VALUE]" help="The value to set the alias to" required=#false
@@ -108,7 +108,7 @@ cmd tool-alias help="Manage tool version aliases." {
     cmd unset help="Clears an alias for a backend/plugin" {
         alias rm remove delete del
         long_help "Clears an alias for a backend/plugin\n\nThis modifies the contents of ~/.config/mise/config.toml"
-        after_long_help "Examples:\n\n    $ mise alias unset maven\n    $ mise alias unset node lts-jod\n"
+        after_long_help "Examples:\n\n    $ mise tool-alias unset maven\n    $ mise tool-alias unset node lts-jod\n"
         arg <PLUGIN> help="The backend/plugin to remove the alias from"
         arg "[ALIAS]" help="The alias to remove" required=#false
     }
@@ -834,6 +834,32 @@ cmd shell help="Sets a tool version for the current session." {
     flag --raw help="Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1"
     arg <TOOL@VERSION>… help="Tool(s) to use" var=#true
 }
+cmd shell-alias help="Manage shell aliases." {
+    flag --no-header help="Don't show table header"
+    cmd get help="Show the command for a shell alias" {
+        after_long_help "Examples:\n\n    $ mise shell-alias get ll\n    ls -la\n"
+        arg <ALIAS> help="The alias to show"
+    }
+    cmd ls help="List shell aliases" {
+        alias list
+        long_help "List shell aliases\n\nShows the shell aliases that are set in the current directory.\nThese are defined in `mise.toml` under the `[shell_alias]` section."
+        after_long_help "Examples:\n\n    $ mise shell-alias ls\n    alias    command\n    ll       ls -la\n    gs       git status\n"
+        flag --no-header help="Don't show table header"
+    }
+    cmd set help="Add/update a shell alias" {
+        alias add create
+        long_help "Add/update a shell alias\n\nThis modifies the contents of ~/.config/mise/config.toml"
+        after_long_help "Examples:\n\n    $ mise shell-alias set ll \"ls -la\"\n    $ mise shell-alias set gs \"git status\"\n"
+        arg <ALIAS> help="The alias name"
+        arg <COMMAND> help="The command to run"
+    }
+    cmd unset help="Removes a shell alias" {
+        alias rm remove delete del
+        long_help "Removes a shell alias\n\nThis modifies the contents of ~/.config/mise/config.toml"
+        after_long_help "Examples:\n\n    $ mise shell-alias unset ll\n"
+        arg <ALIAS> help="The alias to remove"
+    }
+}
 cmd sync subcommand_required=#true help="Synchronize tools from other version managers with mise" {
     cmd node help="Symlinks all tool versions from an external tool into mise" {
         long_help "Symlinks all tool versions from an external tool into mise\n\nFor example, use this to import all Homebrew node installs into mise\n\nThis won't overwrite any existing installs but will overwrite any existing symlinks"
diff --git a/xtasks/fig/src/mise.ts b/xtasks/fig/src/mise.ts
index cbdd7ed027..aa4414a047 100644
--- a/xtasks/fig/src/mise.ts
+++ b/xtasks/fig/src/mise.ts
@@ -562,7 +562,7 @@ const completionSpec: Fig.Spec = {
         {
           name: ["ls", "list"],
           description:
-            "List aliases\nShows the aliases that can be specified.\nThese can come from user config or from plugins in `bin/list-aliases`.",
+            "List tool version aliases\nShows the aliases that can be specified.\nThese can come from user config or from plugins in `bin/list-aliases`.",
           options: [
             {
               name: "--no-header",
@@ -2393,6 +2393,66 @@ const completionSpec: Fig.Spec = {
         debounce: true,
       },
     },
+    {
+      name: "shell-alias",
+      description: "Manage shell aliases.",
+      subcommands: [
+        {
+          name: "get",
+          description: "Show the command for a shell alias",
+          args: {
+            name: "alias",
+            description: "The alias to show",
+            generators: aliasGenerator,
+            debounce: true,
+          },
+        },
+        {
+          name: ["ls", "list"],
+          description: "List shell aliases",
+          options: [
+            {
+              name: "--no-header",
+              description: "Don't show table header",
+              isRepeatable: false,
+            },
+          ],
+        },
+        {
+          name: ["set", "add", "create"],
+          description: "Add/update a shell alias",
+          args: [
+            {
+              name: "alias",
+              description: "The alias name",
+              generators: aliasGenerator,
+              debounce: true,
+            },
+            {
+              name: "command",
+              description: "The command to run",
+            },
+          ],
+        },
+        {
+          name: ["unset", "rm", "remove", "delete", "del"],
+          description: "Removes a shell alias",
+          args: {
+            name: "alias",
+            description: "The alias to remove",
+            generators: aliasGenerator,
+            debounce: true,
+          },
+        },
+      ],
+      options: [
+        {
+          name: "--no-header",
+          description: "Don't show table header",
+          isRepeatable: false,
+        },
+      ],
+    },
     {
       name: "sync",
       description: "Synchronize tools from other version managers with mise",

From 58c42449ac0f7ef0eec1fe07acfd3fbb7804124c Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Wed, 17 Dec 2025 11:17:32 -0600
Subject: [PATCH 7/8] fix(completions): use correct generator for shell-alias
 commands

- Add shellAliasGenerator that runs 'mise shell-alias ls'
- Rename shell-alias args from 'alias' to 'shell_alias' to avoid conflicting with tool alias generator
- Update addCustomGenerators to add generators for matching arg names that don't have them
- Regenerate completions with correct shell alias completions
---
 docs/cli/index.md                 |  6 +++---
 docs/cli/shell-alias.md           |  6 +++---
 docs/cli/shell-alias/get.md       |  4 ++--
 docs/cli/shell-alias/set.md       |  4 ++--
 docs/cli/shell-alias/unset.md     |  4 ++--
 mise.usage.kdl                    |  6 +++---
 src/cli/shell_alias/get.rs        |  1 +
 src/cli/shell_alias/set.rs        |  1 +
 src/cli/shell_alias/unset.rs      |  1 +
 xtasks/fig/addCustomGenerators.ts | 31 +++++++++++++++++++++++++++++++
 xtasks/fig/generators.ts          | 14 ++++++++++++++
 xtasks/fig/src/mise.ts            | 30 ++++++++++++++++++++++++------
 12 files changed, 87 insertions(+), 21 deletions(-)

diff --git a/docs/cli/index.md b/docs/cli/index.md
index d067b07e17..fb2f74c686 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -135,10 +135,10 @@ Can also use `MISE_NO_CONFIG=1`
 - [`mise settings unset [-l --local] <KEY>`](/cli/settings/unset.md)
 - [`mise shell [FLAGS] <TOOL@VERSION>…`](/cli/shell.md)
 - [`mise shell-alias [--no-header] <SUBCOMMAND>`](/cli/shell-alias.md)
-- [`mise shell-alias get <ALIAS>`](/cli/shell-alias/get.md)
+- [`mise shell-alias get <shell_alias>`](/cli/shell-alias/get.md)
 - [`mise shell-alias ls [--no-header]`](/cli/shell-alias/ls.md)
-- [`mise shell-alias set <ALIAS> <COMMAND>`](/cli/shell-alias/set.md)
-- [`mise shell-alias unset <ALIAS>`](/cli/shell-alias/unset.md)
+- [`mise shell-alias set <shell_alias> <COMMAND>`](/cli/shell-alias/set.md)
+- [`mise shell-alias unset <shell_alias>`](/cli/shell-alias/unset.md)
 - [`mise sync <SUBCOMMAND>`](/cli/sync.md)
 - [`mise sync node [FLAGS]`](/cli/sync/node.md)
 - [`mise sync python [--pyenv] [--uv]`](/cli/sync/python.md)
diff --git a/docs/cli/shell-alias.md b/docs/cli/shell-alias.md
index 0136607b4d..0858fb2bb1 100644
--- a/docs/cli/shell-alias.md
+++ b/docs/cli/shell-alias.md
@@ -14,7 +14,7 @@ Don't show table header
 
 ## Subcommands
 
-- [`mise shell-alias get <ALIAS>`](/cli/shell-alias/get.md)
+- [`mise shell-alias get <shell_alias>`](/cli/shell-alias/get.md)
 - [`mise shell-alias ls [--no-header]`](/cli/shell-alias/ls.md)
-- [`mise shell-alias set <ALIAS> <COMMAND>`](/cli/shell-alias/set.md)
-- [`mise shell-alias unset <ALIAS>`](/cli/shell-alias/unset.md)
+- [`mise shell-alias set <shell_alias> <COMMAND>`](/cli/shell-alias/set.md)
+- [`mise shell-alias unset <shell_alias>`](/cli/shell-alias/unset.md)
diff --git a/docs/cli/shell-alias/get.md b/docs/cli/shell-alias/get.md
index 9d6c0f24f2..7680dbed56 100644
--- a/docs/cli/shell-alias/get.md
+++ b/docs/cli/shell-alias/get.md
@@ -1,14 +1,14 @@
 <!-- @generated by usage-cli from usage spec -->
 # `mise shell-alias get`
 
-- **Usage**: `mise shell-alias get <ALIAS>`
+- **Usage**: `mise shell-alias get <shell_alias>`
 - **Source code**: [`src/cli/shell_alias/get.rs`](https://github.com/jdx/mise/blob/main/src/cli/shell_alias/get.rs)
 
 Show the command for a shell alias
 
 ## Arguments
 
-### `<ALIAS>`
+### `<shell_alias>`
 
 The alias to show
 
diff --git a/docs/cli/shell-alias/set.md b/docs/cli/shell-alias/set.md
index 1c7479b01e..514b6aae91 100644
--- a/docs/cli/shell-alias/set.md
+++ b/docs/cli/shell-alias/set.md
@@ -1,7 +1,7 @@
 <!-- @generated by usage-cli from usage spec -->
 # `mise shell-alias set`
 
-- **Usage**: `mise shell-alias set <ALIAS> <COMMAND>`
+- **Usage**: `mise shell-alias set <shell_alias> <COMMAND>`
 - **Aliases**: `add`, `create`
 - **Source code**: [`src/cli/shell_alias/set.rs`](https://github.com/jdx/mise/blob/main/src/cli/shell_alias/set.rs)
 
@@ -11,7 +11,7 @@ This modifies the contents of ~/.config/mise/config.toml
 
 ## Arguments
 
-### `<ALIAS>`
+### `<shell_alias>`
 
 The alias name
 
diff --git a/docs/cli/shell-alias/unset.md b/docs/cli/shell-alias/unset.md
index 2712129634..174870d82d 100644
--- a/docs/cli/shell-alias/unset.md
+++ b/docs/cli/shell-alias/unset.md
@@ -1,7 +1,7 @@
 <!-- @generated by usage-cli from usage spec -->
 # `mise shell-alias unset`
 
-- **Usage**: `mise shell-alias unset <ALIAS>`
+- **Usage**: `mise shell-alias unset <shell_alias>`
 - **Aliases**: `rm`, `remove`, `delete`, `del`
 - **Source code**: [`src/cli/shell_alias/unset.rs`](https://github.com/jdx/mise/blob/main/src/cli/shell_alias/unset.rs)
 
@@ -11,7 +11,7 @@ This modifies the contents of ~/.config/mise/config.toml
 
 ## Arguments
 
-### `<ALIAS>`
+### `<shell_alias>`
 
 The alias to remove
 
diff --git a/mise.usage.kdl b/mise.usage.kdl
index 16951db8a7..4f0bd88184 100644
--- a/mise.usage.kdl
+++ b/mise.usage.kdl
@@ -838,7 +838,7 @@ cmd shell-alias help="Manage shell aliases." {
     flag --no-header help="Don't show table header"
     cmd get help="Show the command for a shell alias" {
         after_long_help "Examples:\n\n    $ mise shell-alias get ll\n    ls -la\n"
-        arg <ALIAS> help="The alias to show"
+        arg <shell_alias> help="The alias to show"
     }
     cmd ls help="List shell aliases" {
         alias list
@@ -850,14 +850,14 @@ cmd shell-alias help="Manage shell aliases." {
         alias add create
         long_help "Add/update a shell alias\n\nThis modifies the contents of ~/.config/mise/config.toml"
         after_long_help "Examples:\n\n    $ mise shell-alias set ll \"ls -la\"\n    $ mise shell-alias set gs \"git status\"\n"
-        arg <ALIAS> help="The alias name"
+        arg <shell_alias> help="The alias name"
         arg <COMMAND> help="The command to run"
     }
     cmd unset help="Removes a shell alias" {
         alias rm remove delete del
         long_help "Removes a shell alias\n\nThis modifies the contents of ~/.config/mise/config.toml"
         after_long_help "Examples:\n\n    $ mise shell-alias unset ll\n"
-        arg <ALIAS> help="The alias to remove"
+        arg <shell_alias> help="The alias to remove"
     }
 }
 cmd sync subcommand_required=#true help="Synchronize tools from other version managers with mise" {
diff --git a/src/cli/shell_alias/get.rs b/src/cli/shell_alias/get.rs
index a5e3d07080..199f1ebed5 100644
--- a/src/cli/shell_alias/get.rs
+++ b/src/cli/shell_alias/get.rs
@@ -7,6 +7,7 @@ use crate::config::Config;
 #[clap(after_long_help = AFTER_LONG_HELP, verbatim_doc_comment)]
 pub struct ShellAliasGet {
     /// The alias to show
+    #[clap(name = "shell_alias")]
     pub alias: String,
 }
 
diff --git a/src/cli/shell_alias/set.rs b/src/cli/shell_alias/set.rs
index 9dee4caf7e..fe34a904da 100644
--- a/src/cli/shell_alias/set.rs
+++ b/src/cli/shell_alias/set.rs
@@ -10,6 +10,7 @@ use crate::config::config_file::ConfigFile;
 #[clap(visible_aliases = ["add", "create"], after_long_help = AFTER_LONG_HELP, verbatim_doc_comment)]
 pub struct ShellAliasSet {
     /// The alias name
+    #[clap(name = "shell_alias")]
     pub alias: String,
     /// The command to run
     pub command: String,
diff --git a/src/cli/shell_alias/unset.rs b/src/cli/shell_alias/unset.rs
index 74ad09b029..1d579e67ed 100644
--- a/src/cli/shell_alias/unset.rs
+++ b/src/cli/shell_alias/unset.rs
@@ -10,6 +10,7 @@ use crate::config::config_file::ConfigFile;
 #[clap(visible_aliases = ["rm", "remove", "delete", "del"], after_long_help = AFTER_LONG_HELP, verbatim_doc_comment)]
 pub struct ShellAliasUnset {
     /// The alias to remove
+    #[clap(name = "shell_alias")]
     pub alias: String,
 }
 
diff --git a/xtasks/fig/addCustomGenerators.ts b/xtasks/fig/addCustomGenerators.ts
index d28299a2b4..edd38f136c 100644
--- a/xtasks/fig/addCustomGenerators.ts
+++ b/xtasks/fig/addCustomGenerators.ts
@@ -15,6 +15,10 @@ const customGenerators: GeneratorIdentifier[] = [
     identifier: "alias",
     generator_name: "aliasGenerator",
   },
+  {
+    identifier: "shell_alias",
+    generator_name: "shellAliasGenerator",
+  },
   {
     identifier: "plugin",
     generator_name: "pluginGenerator",
@@ -126,6 +130,33 @@ function transformer<T extends ts.Node>(context: ts.TransformationContext) {
         }
       }
       const newNode = ts.visitEachChild(node, visit, context);
+      // Add generators to objects that should have them but don't
+      if (
+        newNode &&
+        has_property(newNode, '"name"') &&
+        has_property(newNode, '"description"') &&
+        !has_property(newNode, '"generators"') &&
+        !has_property(newNode, '"subcommands"') &&
+        !has_property(newNode, '"options"')
+      ) {
+        const id = get_identifier(newNode);
+        if (id) {
+          const objLiteralExpr = newNode as ts.ObjectLiteralExpression;
+          const generatorsProperty = ts.factory.createPropertyAssignment(
+            '"generators"',
+            id
+          );
+          const debounceProperty = ts.factory.createPropertyAssignment(
+            '"debounce"',
+            ts.factory.createIdentifier("true")
+          );
+          return ts.factory.updateObjectLiteralExpression(objLiteralExpr, [
+            ...objLiteralExpr.properties,
+            generatorsProperty,
+            debounceProperty,
+          ]);
+        }
+      }
       if (
         newNode &&
         has_property(newNode, '"generators"') &&
diff --git a/xtasks/fig/generators.ts b/xtasks/fig/generators.ts
index d90b05291b..f193c21290 100644
--- a/xtasks/fig/generators.ts
+++ b/xtasks/fig/generators.ts
@@ -50,6 +50,20 @@ const aliasGenerator: Fig.Generator = {
   },
 };
 
+const shellAliasGenerator: Fig.Generator = {
+  script: ["sh", "-c", "mise shell-alias ls --no-header"],
+  postProcess: (out) => {
+    if (!out.trim()) return [];
+    return out
+      .split("\n")
+      .filter((l) => l.trim().length > 0)
+      .map((l) => {
+        const tokens = l.split(/\s+/);
+        return { name: tokens[0], description: tokens.slice(1).join(" ") };
+      });
+  },
+};
+
 const pluginWithAlias: Fig.Generator = {
   script: "mise alias ls".split(" "),
   postProcess: (output: string) => {
diff --git a/xtasks/fig/src/mise.ts b/xtasks/fig/src/mise.ts
index aa4414a047..28ecc77046 100644
--- a/xtasks/fig/src/mise.ts
+++ b/xtasks/fig/src/mise.ts
@@ -50,6 +50,20 @@ const aliasGenerator: Fig.Generator = {
   },
 };
 
+const shellAliasGenerator: Fig.Generator = {
+  script: ["sh", "-c", "mise shell-alias ls --no-header"],
+  postProcess: (out) => {
+    if (!out.trim()) return [];
+    return out
+      .split("\n")
+      .filter((l) => l.trim().length > 0)
+      .map((l) => {
+        const tokens = l.split(/\s+/);
+        return { name: tokens[0], description: tokens.slice(1).join(" ") };
+      });
+  },
+};
+
 const pluginWithAlias: Fig.Generator = {
   script: "mise alias ls".split(" "),
   postProcess: (output: string) => {
@@ -2401,9 +2415,9 @@ const completionSpec: Fig.Spec = {
           name: "get",
           description: "Show the command for a shell alias",
           args: {
-            name: "alias",
+            name: "shell_alias",
             description: "The alias to show",
-            generators: aliasGenerator,
+            generators: shellAliasGenerator,
             debounce: true,
           },
         },
@@ -2423,9 +2437,9 @@ const completionSpec: Fig.Spec = {
           description: "Add/update a shell alias",
           args: [
             {
-              name: "alias",
+              name: "shell_alias",
               description: "The alias name",
-              generators: aliasGenerator,
+              generators: shellAliasGenerator,
               debounce: true,
             },
             {
@@ -2438,9 +2452,9 @@ const completionSpec: Fig.Spec = {
           name: ["unset", "rm", "remove", "delete", "del"],
           description: "Removes a shell alias",
           args: {
-            name: "alias",
+            name: "shell_alias",
             description: "The alias to remove",
-            generators: aliasGenerator,
+            generators: shellAliasGenerator,
             debounce: true,
           },
         },
@@ -2664,6 +2678,8 @@ const completionSpec: Fig.Spec = {
               "Tasks to show dependencies for\nCan specify multiple tasks by separating with spaces\ne.g.: mise tasks deps lint test check",
             isOptional: true,
             isVariadic: true,
+            generators: simpleTaskGenerator,
+            debounce: true,
           },
         },
         {
@@ -2916,6 +2932,8 @@ const completionSpec: Fig.Spec = {
               "Tasks to validate\nIf not specified, validates all tasks",
             isOptional: true,
             isVariadic: true,
+            generators: simpleTaskGenerator,
+            debounce: true,
           },
         },
       ],

From d9643539d6237ad448a721552d70836d9ce40132 Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Wed, 17 Dec 2025 17:27:44 +0000
Subject: [PATCH 8/8] [autofix.ci] apply automated fixes

---
 man/man1/mise.1 | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/man/man1/mise.1 b/man/man1/mise.1
index 915aa9f360..b345f514aa 100644
--- a/man/man1/mise.1
+++ b/man/man1/mise.1
@@ -2146,12 +2146,12 @@ Don't show table header
 .SH "MISE SHELL-ALIAS GET"
 Show the command for a shell alias
 .PP
-\fBUsage:\fR mise shell\-alias get <ALIAS>
+\fBUsage:\fR mise shell\-alias get <shell_alias>
 .PP
 \fBArguments:\fR
 .PP
 .TP
-\fB<ALIAS>\fR
+\fB<shell_alias>\fR
 The alias to show
 .SH "MISE SHELL-ALIAS LS"
 List shell aliases
@@ -2171,12 +2171,12 @@ Add/update a shell alias
 
 This modifies the contents of ~/.config/mise/config.toml
 .PP
-\fBUsage:\fR mise shell\-alias set <ALIAS> <COMMAND>
+\fBUsage:\fR mise shell\-alias set <shell_alias> <COMMAND>
 .PP
 \fBArguments:\fR
 .PP
 .TP
-\fB<ALIAS>\fR
+\fB<shell_alias>\fR
 The alias name
 .TP
 \fB<COMMAND>\fR
@@ -2186,12 +2186,12 @@ Removes a shell alias
 
 This modifies the contents of ~/.config/mise/config.toml
 .PP
-\fBUsage:\fR mise shell\-alias unset <ALIAS>
+\fBUsage:\fR mise shell\-alias unset <shell_alias>
 .PP
 \fBArguments:\fR
 .PP
 .TP
-\fB<ALIAS>\fR
+\fB<shell_alias>\fR
 The alias to remove
 .SH "MISE SYNC NODE"
 Symlinks all tool versions from an external tool into mise