feat(complete): auto-completion for usage shebang scripts

.github/workflows/autofix.yml

@@ -24,5 +24,12 @@ jobs:
           shared-key: test
           save-if: false
       - uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4
+      - name: Install shells for completion integration tests
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y zsh fish
+          if ! command -v pwsh >/dev/null 2>&1; then
+            sudo snap install powershell --classic
+          fi
       - run: mise r autofix
       - uses: autofix-ci/action@c5b2d67aa2274e7b5a18224e8171550871fc7e4a # v1.3.4

.github/workflows/coverage.yml

@@ -23,6 +23,13 @@ jobs:
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
       - name: Install cargo-llvm-cov
         uses: taiki-e/install-action@fc9eae0a7877a2f4152f841721d1d1aa8c3f1a27 # cargo-llvm-cov
+      - name: Install shells for completion integration tests
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y zsh fish
+          if ! command -v pwsh >/dev/null 2>&1; then
+            sudo snap install powershell --classic
+          fi
       - name: Generate code coverage
         run: mise run coverage
       - name: Upload coverage to Codecov

.github/workflows/test.yml

@@ -23,6 +23,16 @@ jobs:
         with:
           shared-key: test
       - uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4
+      - name: Install shells for completion integration tests
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y zsh fish
+          # pwsh is pre-installed on GitHub ubuntu-latest images. Self-heal
+          # if a future image drops it so the integration test still runs
+          # (rather than panicking under CI=1).
+          if ! command -v pwsh >/dev/null 2>&1; then
+            sudo snap install powershell --classic
+          fi
       - run: mise r build
       - run: mise r test
       - run: mise r lint

cli/assets/fig.ts

@@ -286,6 +286,27 @@ const completionSpec: Fig.Spec = {
             },
           ],
         },
+        {
+          name: ["completion-init", "ci"],
+          description:
+            "Generate a shell init script that auto-completes any usage shebang script on $PATH",
+          options: [
+            {
+              name: "--usage-bin",
+              description:
+                "Override the bin used for calling back to usage-cli",
+              isRepeatable: false,
+              args: {
+                name: "usage_bin",
+              },
+            },
+          ],
+          args: {
+            name: "shell",
+            description: "Shell to generate the init script for",
+            suggestions: ["bash", "fish", "zsh"],
+          },
+        },
         {
           name: "fig",
           description: "Generate Fig completion spec for Amazon Q / Fig",

cli/assets/usage.1

@@ -46,6 +46,12 @@ Generate shell completion scripts for bash, fish, nu, powershell, or zsh
 \fIAliases: \fRc
 .RE
 .TP
+\fBgenerate completion\-init\fR
+Generate a shell init script that auto\-completes any usage shebang script on $PATH
+.RS
+\fIAliases: \fRci
+.RE
+.TP
 \fBgenerate fig\fR
 Generate Fig completion spec for Amazon Q / Fig
 .TP
@@ -206,6 +212,28 @@ Shell to generate completions for
 .TP
 \fB<BIN>\fR
 The CLI which we're generating completions for
+.SH "USAGE GENERATE COMPLETION-INIT"
+Generate a shell init script that auto\-completes any usage shebang script on $PATH
+
+Source the output once from your shell rc (e.g. ~/.bashrc) to enable tab\-completion for any executable whose first line is a `usage` shebang — no per\-script `usage g completion` step required.
+.PP
+\fBUsage:\fR usage generate completion\-init [OPTIONS] <SHELL>
+.PP
+\fBOptions:\fR
+.PP
+.TP
+\fB\-\-usage\-bin\fR \fI<USAGE_BIN>\fR
+Override the bin used for calling back to usage\-cli
+
+You may need to set this if you have a different bin named "usage"
+.RS
+\fIDefault: \fRusage
+.RE
+\fBArguments:\fR
+.PP
+.TP
+\fB<SHELL>\fR
+Shell to generate the init script for
 .SH "USAGE GENERATE FIG"
 Generate Fig completion spec for Amazon Q / Fig
 .PP

cli/src/cli/generate/completion_init.rs

@@ -0,0 +1,28 @@
+use clap::Args;
+use usage::complete::complete_init;
+
+/// Generate a shell init script that auto-completes any usage shebang script on $PATH
+///
+/// Source the output once from your shell rc (e.g. ~/.bashrc) to enable
+/// tab-completion for any executable whose first line is a `usage` shebang —
+/// no per-script `usage g completion` step required.
+#[derive(Args)]
+#[clap(visible_alias = "ci", aliases = ["init", "completions-init"])]
+pub struct CompletionInit {
+    /// Shell to generate the init script for
+    #[clap(value_parser = ["bash", "fish", "zsh"])]
+    shell: String,
+
+    /// Override the bin used for calling back to usage-cli
+    ///
+    /// You may need to set this if you have a different bin named "usage"
+    #[clap(long, default_value = "usage", env = "JDX_USAGE_BIN")]
+    usage_bin: String,
+}
+
+impl CompletionInit {
+    pub fn run(&self) -> miette::Result<()> {
+        println!("{}", complete_init(&self.shell, &self.usage_bin)?.trim());
+        Ok(())
+    }
+}

cli/src/cli/generate/mod.rs

@@ -5,6 +5,7 @@ use usage::error::UsageErr;
 use usage::Spec;
 
 mod completion;
+mod completion_init;
 mod fig;
 mod json;
 mod manpage;
@@ -21,6 +22,7 @@ pub struct Generate {
 #[derive(clap::Subcommand)]
 pub enum Command {
     Completion(completion::Completion),
+    CompletionInit(completion_init::CompletionInit),
     Fig(fig::Fig),
     Json(json::Json),
     Manpage(manpage::Manpage),
@@ -31,6 +33,7 @@ impl Generate {
     pub fn run(&self) -> miette::Result<()> {
         match &self.command {
             Command::Completion(cmd) => cmd.run(),
+            Command::CompletionInit(cmd) => cmd.run(),
             Command::Fig(cmd) => cmd.run(),
             Command::Json(cmd) => cmd.run(),
             Command::Manpage(cmd) => cmd.run(),