feat(cli): add shell completion command

Author: pallyoung

README.en.md

@@ -77,6 +77,8 @@ coder-studio config password set --stdin
 coder-studio auth status
 coder-studio auth ip list
 coder-studio help start
+coder-studio help completion
+eval "$(coder-studio completion bash)"
 ```
 
 For the detailed command reference, see `docs/development/cli.en.md`.

README.md

@@ -76,6 +76,8 @@ coder-studio config password set --stdin
 coder-studio auth status
 coder-studio auth ip list
 coder-studio help start
+coder-studio help completion
+eval "$(coder-studio completion bash)"
 ```
 
 详细命令说明见：`docs/development/cli.md`

docs/development/cli.en.md

@@ -74,6 +74,14 @@ coder-studio auth ip unblock 203.0.113.12
 coder-studio auth ip unblock --all
 ```
 
+Shell completion:
+
+```bash
+coder-studio completion bash
+coder-studio completion zsh
+coder-studio completion fish
+```
+
 Version:
 
 ```bash
@@ -87,6 +95,7 @@ coder-studio help
 coder-studio help start
 coder-studio help config
 coder-studio help auth
+coder-studio help completion
 ```
 
 ## Global Flags
@@ -105,6 +114,31 @@ Additional flags on specific commands:
 - `config password set --stdin`: reads the passphrase from stdin
 - `auth ip unblock --all`: removes all currently blocked IPs at once
 
+## Shell Completion
+
+The CLI can print completion scripts for `bash`, `zsh`, and `fish`. The command only writes the script to stdout.
+
+Load it for the current shell session:
+
+```bash
+eval "$(coder-studio completion bash)"
+source <(coder-studio completion zsh)
+coder-studio completion fish | source
+```
+
+Persistent installation examples:
+
+```bash
+coder-studio completion bash >> ~/.bashrc
+coder-studio completion zsh > ~/.zfunc/_coder-studio
+coder-studio completion fish > ~/.config/fish/completions/coder-studio.fish
+```
+
+Notes:
+
+- `completion` does not support `--json`
+- `coder-studio help completion` shows command usage
+
 ## Exit Codes
 
 - `0`: success

docs/development/cli.md

@@ -74,6 +74,14 @@ coder-studio auth ip unblock 203.0.113.12
 coder-studio auth ip unblock --all
 ```
 
+Shell Completion：
+
+```bash
+coder-studio completion bash
+coder-studio completion zsh
+coder-studio completion fish
+```
+
 版本信息：
 
 ```bash
@@ -87,6 +95,7 @@ coder-studio help
 coder-studio help start
 coder-studio help config
 coder-studio help auth
+coder-studio help completion
 ```
 
 ## 全局参数
@@ -105,6 +114,31 @@ coder-studio help auth
 - `config password set --stdin`：从标准输入读取口令
 - `auth ip unblock --all`：一次解除全部当前封禁 IP
 
+## Shell Completion
+
+CLI 可以输出 `bash`、`zsh`、`fish` 的补全脚本，命令本身只负责把脚本打印到标准输出。
+
+即时加载：
+
+```bash
+eval "$(coder-studio completion bash)"
+source <(coder-studio completion zsh)
+coder-studio completion fish | source
+```
+
+持久化安装示例：
+
+```bash
+coder-studio completion bash >> ~/.bashrc
+coder-studio completion zsh > ~/.zfunc/_coder-studio
+coder-studio completion fish > ~/.config/fish/completions/coder-studio.fish
+```
+
+说明：
+
+- `completion` 不支持 `--json`
+- `coder-studio help completion` 可查看命令说明
+
 ## 退出码
 
 - `0`：执行成功

packages/coder-studio/lib/cli.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises';
+import { generateCompletionScript, SUPPORTED_COMPLETION_SHELLS } from './completion.mjs';
 import { resolveLogPath } from './config.mjs';
 import {
   buildConfigPathsReport,
@@ -106,6 +107,7 @@ Usage:
   coder-studio doctor [--json]
   coder-studio config <subcommand>
   coder-studio auth <subcommand>
+  coder-studio completion <bash|zsh|fish>
   coder-studio --version
 
 Global Flags:
@@ -121,12 +123,14 @@ Exit Codes:
 
 Examples:
   coder-studio help start
+  coder-studio help completion
   coder-studio start
   coder-studio config show --json
   coder-studio config root set /srv/coder-studio/workspaces
   coder-studio auth ip list
+  eval "$(coder-studio completion bash)"
 
-Run \`coder-studio config --help\` or \`coder-studio auth --help\` for detailed usage.
+Run \`coder-studio config --help\`, \`coder-studio auth --help\`, or \`coder-studio help completion\` for detailed usage.
 `);
 }
 
@@ -291,6 +295,22 @@ Examples:
 `);
 }
 
+function printCompletionHelp() {
+  console.log(`coder-studio completion
+
+Usage:
+  coder-studio completion <bash|zsh|fish>
+
+Description:
+  Print a shell completion script to stdout. Evaluate or source the output in your shell profile.
+
+Examples:
+  eval "$(coder-studio completion bash)"
+  source <(coder-studio completion zsh)
+  coder-studio completion fish | source
+`);
+}
+
 function printHelpTopic(topic) {
   switch (topic) {
     case undefined:
@@ -326,6 +346,9 @@ function printHelpTopic(topic) {
     case 'auth':
       printAuthHelp();
       return EXIT_SUCCESS;
+    case 'completion':
+      printCompletionHelp();
+      return EXIT_SUCCESS;
     default:
       throw usageError(`unsupported help topic: ${topic}`, 'main');
   }
@@ -884,6 +907,8 @@ function printCliError(error, flags) {
     console.error('hint: run `coder-studio config --help`');
   } else if (normalized.helpTopic === 'auth') {
     console.error('hint: run `coder-studio auth --help`');
+  } else if (normalized.helpTopic === 'completion') {
+    console.error('hint: run `coder-studio help completion`');
   } else if (normalized.helpTopic === 'main') {
     console.error('hint: run `coder-studio help`');
   }
@@ -907,6 +932,27 @@ export async function runCli(argv = process.argv.slice(2)) {
       return printHelpTopic(command);
     }
 
+    if (command === 'completion') {
+      if (flags.json) {
+        throw usageError('completion does not support --json', 'completion');
+      }
+
+      const [shell, ...rest] = positionals;
+      if (!shell) {
+        printCompletionHelp();
+        return EXIT_SUCCESS;
+      }
+      if (rest.length > 0) {
+        throw usageError('completion accepts exactly one <shell> argument', 'completion');
+      }
+      if (!SUPPORTED_COMPLETION_SHELLS.includes(shell)) {
+        throw usageError(`unsupported completion shell: ${shell}`, 'completion');
+      }
+
+      process.stdout.write(generateCompletionScript(shell));
+      return EXIT_SUCCESS;
+    }
+
     if (command === 'config') {
       const context = await resolveCommandContext(flags);
       return await handleConfigCommand(positionals, flags, context);