Add completion-cmds for shell completion

Add a new `dist.completion-cmds` option which takes a map of binary
names to the subcommand to execute to generate shell completions.

This hooks in very easily with the Homebrew
`generate_completions_from_executable` helper function. We allow three
options for completion generation, `clap-env`, which will use
`clap_complete`'s environment variable option to trigger shell
completion, or `subcommand`, which specifies the subcommand and
parameter format, flag or arg, for the command. All options take an
array of shells.

  ```toml
  [dist.completion-cmds.mybin]
  trigger = "clap-env"
  shells = ["bash","fish"]

  [dist.completion-cmds.otherbin]
  trigger.subcommand = {{ name = "completions", format = "flag" }}
  shells = ["bash","fish","pwsh","zsh"]
  ```

Author: wfchandler

CHANGELOG.md

@@ -5,6 +5,19 @@ Nothing Yet!
 # Version 1.0.6 (2025-07-03)
 
 - Change committer of Homebrew formulas to the owner of GITHUB_TOKEN.
+- Add `dist.completion-cmds` option. This takes a map of binaries and a corresponding subcommand which can be executed to generate shell completions. Completions for `bash`, `zsh`, and `fish` will be installed. Currently this only used for Homebrew installs.
+
+Example configs:
+
+```toml
+[dist.completion-cmds.mybin]
+trigger = "clap-env"
+shells = ["bash","fish"]
+
+[dist.completion-cmds.otherbin]
+trigger.subcommand = {{ name = "completions", format = "flag" }}
+shells = ["bash","fish","pwsh","zsh"]
+```
 
 # Version 1.0.5 (2025-07-02)
 

cargo-dist/src/backend/installer/homebrew.rs

@@ -1,5 +1,7 @@
 //! Code for generating formula.rb
 
+use std::collections::BTreeMap;
+
 use axoasset::LocalAsset;
 use dist_schema::{ChecksumValue, DistManifest, HomebrewPackageName};
 use serde::Serialize;
@@ -11,7 +13,7 @@ use spdx::{
 use super::InstallerInfo;
 use crate::{
     backend::templates::TEMPLATE_INSTALLER_RB,
-    config::{ChecksumStyle, LibraryStyle},
+    config::{ChecksumStyle, CompletionTrigger, LibraryStyle, ParamFormat},
     errors::DistResult,
     installer::ExecutableZipFragment,
     tasks::DistGraph,
@@ -92,8 +94,40 @@ pub(crate) fn write_homebrew_formula(
     }
     map_fragments!(fragments = (arm64_linux, x86_64_linux, arm64_macos, x86_64_macos));
 
+    let mut completions = BTreeMap::new();
+    for (bin, cmp) in &info.inner.completion_cmds {
+        let mut shells = "[".to_string();
+        let mut shell_iter = cmp.shells.iter().peekable();
+        while let Some(shell) = shell_iter.next() {
+            shells += &format!(":{shell}");
+            if shell_iter.peek().is_some() {
+                shells.push_str(", ");
+            }
+        }
+        shells.push(']');
+
+        let (subcommand, format) = match cmp.trigger.clone() {
+            CompletionTrigger::ClapEnv => (None, ":clap"),
+            CompletionTrigger::Subcommand { name, format } => match format {
+                ParamFormat::Arg => (Some(name), ":arg"),
+                ParamFormat::Flag => (Some(name), ":flag"),
+            },
+        };
+
+        let completion = match subcommand {
+            Some(cmd) => format!(" \"{cmd}\", shell_parameter_format: {format}, shells: {shells}"),
+            None => format!("shell_parameter_format: {format}, shells: {shells}"),
+        };
+
+        completions.insert(bin.clone(), completion);
+    }
+
     let dest_path = info.inner.dest_path.clone();
-    let inputs = HomebrewTemplateInputs { info, fragments };
+    let inputs = HomebrewTemplateInputs {
+        info,
+        fragments,
+        completions,
+    };
 
     let script = dist
         .templates
@@ -109,6 +143,8 @@ struct HomebrewTemplateInputs {
 
     #[serde(flatten)]
     fragments: HomebrewFragments<HomebrewFragment>,
+
+    completions: BTreeMap<String, String>,
 }
 
 #[derive(Debug, Clone, Serialize)]

cargo-dist/src/backend/installer/mod.rs

@@ -11,7 +11,7 @@ use macpkg::PkgInstallerInfo;
 use serde::Serialize;
 
 use crate::{
-    config::{JinjaInstallPathStrategy, LibraryStyle, ZipStyle},
+    config::{CompletionConfig, JinjaInstallPathStrategy, LibraryStyle, ZipStyle},
     platform::{PlatformSupport, RuntimeConditions},
     InstallReceipt, ReleaseIdx,
 };
@@ -85,6 +85,8 @@ pub struct InstallerInfo {
     pub receipt: Option<InstallReceipt>,
     /// Aliases to install binaries under
     pub bin_aliases: BTreeMap<TripleName, BTreeMap<String, Vec<String>>>,
+    /// The command to execute to generate shell completion scripts for a given binary
+    pub completion_cmds: BTreeMap<String, CompletionConfig>,
     /// Whether to install generated C dynamic libraries
     pub install_libraries: Vec<LibraryStyle>,
     /// Platform-specific runtime conditions

cargo-dist/src/config/mod.rs

@@ -44,6 +44,66 @@ pub enum GithubPermission {
     Admin,
 }
 
+/// Config for generating shell completions
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, PartialOrd, Ord, Eq)]
+#[serde(rename_all = "kebab-case")]
+pub struct CompletionConfig {
+    /// The method used to trigger shell completions.
+    pub trigger: CompletionTrigger,
+    /// The shells completion should be generated for.
+    pub shells: Vec<Shell>,
+}
+
+/// The method used to trigger shell completions
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, PartialOrd, Ord, Eq)]
+#[serde(rename_all = "kebab-case")]
+pub enum CompletionTrigger {
+    /// Clap completions enabled via the environment, e.g. `COMPLETE=bash foo`.
+    ClapEnv,
+    /// The name of the subcommand to generate shell completions and the parameter format it uses.
+    Subcommand {
+        /// The name of the completion subcommand.
+        name: String,
+        /// The format of the shell-type parameter of the subcommand.
+        format: ParamFormat,
+    },
+}
+
+/// The format of the parameter that specifies the shell type to the completion subcommand
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, PartialOrd, Ord, Eq)]
+#[serde(rename_all = "kebab-case")]
+pub enum ParamFormat {
+    /// Arg, e.g. `foo completions bash`.
+    Arg,
+    /// Flag, e.g. `foo completions --bash`.
+    Flag,
+}
+
+/// The type of shells that completions may be generated for
+#[derive(Debug, Copy, Clone, Serialize, Deserialize, PartialEq, PartialOrd, Ord, Eq)]
+#[serde(rename_all = "kebab-case")]
+pub enum Shell {
+    /// Bash
+    Bash,
+    /// Fish
+    Fish,
+    /// Powershell
+    Pwsh,
+    /// Zsh
+    Zsh,
+}
+
+impl std::fmt::Display for Shell {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Bash => write!(f, "bash"),
+            Self::Fish => write!(f, "fish"),
+            Self::Pwsh => write!(f, "pwsh"),
+            Self::Zsh => write!(f, "zsh"),
+        }
+    }
+}
+
 /// Global config for commands
 #[derive(Debug, Clone)]
 pub struct Config {

cargo-dist/src/config/v0.rs

@@ -490,6 +490,10 @@ pub struct DistMetadata {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub bin_aliases: Option<SortedMap<String, Vec<String>>>,
 
+    /// The command to execute to generate shell completion scripts for a given binary
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub completion_cmds: Option<SortedMap<String, CompletionConfig>>,
+
     /// a prefix to add to the release.yml and tag pattern so that
     /// dist can co-exist with other release workflows in complex workspaces
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -608,6 +612,7 @@ impl DistMetadata {
             github_custom_runners: _,
             github_custom_job_permissions: _,
             bin_aliases: _,
+            completion_cmds: _,
             tag_namespace: _,
             install_updater: _,
             always_use_latest_updater: _,
@@ -710,6 +715,7 @@ impl DistMetadata {
             github_custom_runners,
             github_custom_job_permissions,
             bin_aliases,
+            completion_cmds,
             tag_namespace,
             install_updater,
             always_use_latest_updater,
@@ -894,6 +900,9 @@ impl DistMetadata {
         if bin_aliases.is_none() {
             bin_aliases.clone_from(&workspace_config.bin_aliases);
         }
+        if completion_cmds.is_none() {
+            completion_cmds.clone_from(&workspace_config.completion_cmds);
+        }
         if install_updater.is_none() {
             *install_updater = workspace_config.install_updater;
         }

cargo-dist/src/config/v0_to_v1.rs

@@ -76,6 +76,7 @@ impl DistMetadata {
             github_custom_runners,
             github_custom_job_permissions,
             bin_aliases,
+            completion_cmds,
             tag_namespace,
             install_updater,
             always_use_latest_updater,
@@ -324,6 +325,7 @@ impl DistMetadata {
                 install_success_msg,
                 install_libraries,
                 bin_aliases,
+                completion_cmds,
             },
             homebrew: homebrew_installer_layer,
             msi: msi_installer_layer,

cargo-dist/src/config/v1/installers/mod.rs

@@ -263,6 +263,10 @@ pub struct CommonInstallerLayer {
     /// Aliases to install binaries as
     #[serde(skip_serializing_if = "Option::is_none")]
     pub bin_aliases: Option<SortedMap<String, Vec<String>>>,
+
+    /// The command to execute to generate shell completion scripts for a given binary
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub completion_cmds: Option<SortedMap<String, CompletionConfig>>,
 }
 /// inheritable installer fields (final)
 #[derive(Debug, Default, Clone)]
@@ -291,6 +295,9 @@ pub struct CommonInstallerConfig {
     /// Aliases to install binaries as
     pub bin_aliases: SortedMap<String, Vec<String>>,
 
+    /// The command to execute to generate shell completion scripts for a given binary
+    pub completion_cmds: SortedMap<String, CompletionConfig>,
+
     /// Whether to install an updater program alongside the software
     pub install_updater: bool,
 }
@@ -302,6 +309,7 @@ impl CommonInstallerConfig {
             install_success_msg: "everything's installed!".to_owned(),
             install_libraries: Default::default(),
             bin_aliases: Default::default(),
+            completion_cmds: Default::default(),
             install_updater: false,
         }
     }
@@ -315,12 +323,14 @@ impl ApplyLayer for CommonInstallerConfig {
             install_success_msg,
             install_libraries,
             bin_aliases,
+            completion_cmds,
         }: Self::Layer,
     ) {
         self.install_path.apply_val(install_path);
         self.install_success_msg.apply_val(install_success_msg);
         self.install_libraries.apply_val(install_libraries);
         self.bin_aliases.apply_val(bin_aliases);
+        self.completion_cmds.apply_val(completion_cmds);
     }
 }
 impl ApplyLayer for CommonInstallerLayer {
@@ -332,11 +342,13 @@ impl ApplyLayer for CommonInstallerLayer {
             install_success_msg,
             install_libraries,
             bin_aliases,
+            completion_cmds,
         }: Self::Layer,
     ) {
         self.install_path.apply_opt(install_path);
         self.install_success_msg.apply_opt(install_success_msg);
         self.install_libraries.apply_opt(install_libraries);
         self.bin_aliases.apply_opt(bin_aliases);
+        self.completion_cmds.apply_opt(completion_cmds);
     }
 }

cargo-dist/src/init/v0.rs

@@ -240,6 +240,7 @@ fn get_new_dist_metadata(
             github_custom_runners: None,
             github_custom_job_permissions: None,
             bin_aliases: None,
+            completion_cmds: None,
             tag_namespace: None,
             install_updater: None,
             always_use_latest_updater: None,
@@ -753,6 +754,7 @@ fn apply_dist_to_metadata(metadata: &mut toml_edit::Item, meta: &DistMetadata) {
         github_custom_runners: _,
         github_custom_job_permissions: _,
         bin_aliases: _,
+        completion_cmds: _,
         system_dependencies: _,
         github_build_setup: _,
     } = &meta;

cargo-dist/src/tasks/mod.rs

@@ -2034,6 +2034,7 @@ impl<'pkg_graph> DistGraphBuilder<'pkg_graph> {
                 desc,
                 receipt: InstallReceipt::from_metadata(&self.inner, release)?,
                 bin_aliases,
+                completion_cmds: config.completion_cmds.clone(),
                 install_libraries: config.install_libraries.clone(),
                 runtime_conditions,
                 platform_support: None,
@@ -2172,6 +2173,7 @@ impl<'pkg_graph> DistGraphBuilder<'pkg_graph> {
             desc,
             receipt: None,
             bin_aliases,
+            completion_cmds: config.completion_cmds.clone(),
             install_libraries: config.install_libraries.clone(),
             runtime_conditions,
             platform_support: None,
@@ -2277,6 +2279,7 @@ impl<'pkg_graph> DistGraphBuilder<'pkg_graph> {
                 desc,
                 receipt: InstallReceipt::from_metadata(&self.inner, release)?,
                 bin_aliases,
+                completion_cmds: config.completion_cmds.clone(),
                 install_libraries: config.install_libraries.clone(),
                 runtime_conditions: RuntimeConditions::default(),
                 platform_support: None,
@@ -2394,6 +2397,7 @@ impl<'pkg_graph> DistGraphBuilder<'pkg_graph> {
                     desc,
                     receipt: None,
                     bin_aliases,
+                    completion_cmds: config.completion_cmds.clone(),
                     install_libraries: config.install_libraries.clone(),
                     runtime_conditions,
                     platform_support: None,

cargo-dist/templates/installer/homebrew.rb.j2

@@ -92,6 +92,11 @@ class {{ formula_class }} < Formula
 
     install_binary_aliases!
 
+    {%- for binary, completion_cmd in completions|items %}
+    generate_completions_from_executable(bin/"{{ binary }}",
+                                         {{ completion_cmd }})
+    {%- endfor %}
+
     # Homebrew will automatically install these, so we don't need to do that
     doc_files = Dir["README.*", "readme.*", "LICENSE", "LICENSE.*", "CHANGELOG.*"]
     leftover_contents = Dir["*"] - doc_files