CLI开发工具【免费下载链接】cliA declarative, simple, fast, and fun package for building command line tools in Go项目地址https://gitcode.com/gh_mirrors/cli1/cli点击查看免费下载导读本指南以 urfave/cli v2 官方文档 docs/v2/examples/bash-completions.md 为核心骨架系统讲解如何在 Go CLI 程序中开启 bash 自动补全Auto-completion包括通过EnableBashCompletion一键获得子命令补全、为 App 或子命令编写自定义补全逻辑、利用仓库内置的补全脚本完成当前会话或持久化启用以及将补全能力分发到 zsh、PowerShell 等多个 Shell。读完本文你将能在自己的 urfave/cli 项目中快速落地一套开箱即用的 Shell 补全体验并理解其底层工作机制。适用版本说明本文主体基于github.com/urfave/cli/v2当前仓库go.mod声明模块为github.com/urfave/cli/v3仓库同时保留 v1/v2/v3 三套文档。文末会额外给出 v2→v3 的补全 API 迁移对照便于在 docs/migrate-v2-to-v3.md 与 docs/v3/examples/completions/shell-completions.md 中对照阅读。一、补全机制概览一个开关两套脚本在 urfave/cli v2 中Bash 补全由两部分协作完成程序侧在cli.App上设置EnableBashCompletion: true框架即注册一个隐藏的补全触发 flag默认名为--generate-bash-completion。当用户按下Tab时补全脚本会以该 flag 再次调用你的程序程序进入补全模式输出候选词列表脚本再将候选词回填到命令行。Shell 侧仓库内置了 autocomplete/bash_autocomplete 与 autocomplete/zsh_autocomplete、autocomplete/powershell_autocomplete.ps1 等脚本负责拦截Tab键、调用程序并渲染补全结果。官方文档明确指出开启EnableBashCompletion后默认行为是自动补全App 的子命令你也可以为 App 或其子命令编写自定义的补全方法BashComplete回调实现任意候选词的补全。二、默认自动补全一个开关搞定子命令提示2.1 完整示例代码以下是一个典型的任务清单CLI它定义了add、complete、template三个子命令其中template还嵌套了add、remove两个二级子命令package main import ( fmt log os github.com/urfave/cli/v2 ) func main() { app : cli.App{ EnableBashCompletion: true, Commands: []*cli.Command{ { Name: add, Aliases: []string{a}, Usage: add a task to the list, Action: func(cCtx *cli.Context) error { fmt.Println(added task: , cCtx.Args().First()) return nil }, }, { Name: complete, Aliases: []string{c}, Usage: complete a task on the list, Action: func(cCtx *cli.Context) error { fmt.Println(completed task: , cCtx.Args().First()) return nil }, }, { Name: template, Aliases: []string{t}, Usage: options for task templates, Subcommands: []*cli.Command{ { Name: add, Usage: add a new template, Action: func(cCtx *cli.Context) error { fmt.Println(new task template: , cCtx.Args().First()) return nil }, }, { Name: remove, Usage: remove an existing template, Action: func(cCtx *cli.Context) error { fmt.Println(removed task template: , cCtx.Args().First()) return nil }, }, }, }, }, } if err : app.Run(os.Args); err ! nil { log.Fatal(err) } }2.2 要点拆解EnableBashCompletion: true是唯一需要新增的配置其余代码与普通 CLI 完全相同。默认补全覆盖顶层add、complete、template以及帮助命令help二级在template之后按Tab会补全add、remove别名同样会出现在补全候选里如a、c、t。Action回调中使用cCtx.Args().First()取首个位置参数与补全逻辑互不干扰。编译并执行后你输入tmTab即会补全为template输入template Tab则会提示add与remove这就是框架基于命令树自动生成的补全。三、自定义自动补全用 BashComplete 输出任意候选词默认补全只覆盖子命令当子命令的参数是有限集合时例如任务名称、模板名你需要自定义补全逻辑。在 v2 中通过为cli.Command设置BashComplete回调实现。3.1 完整示例代码下面这个程序维护一份任务列表tasks并让complete子命令在没有位置参数时输出所有任务名作为补全候选package main import ( fmt log os github.com/urfave/cli/v2 ) func main() { tasks : []string{cook, clean, laundry, eat, sleep, code} app : cli.App{ EnableBashCompletion: true, Commands: []*cli.Command{ { Name: complete, Aliases: []string{c}, Usage: complete a task on the list, Action: func(cCtx *cli.Context) error { fmt.Println(completed task: , cCtx.Args().First()) return nil }, BashComplete: func(cCtx *cli.Context) { // This will complete if no args are passed if cCtx.NArg() 0 { return } for _, t : range tasks { fmt.Println(t) } }, }, }, } if err : app.Run(os.Args); err ! nil { log.Fatal(err) } }3.2 BashComplete 回调的约定回调签名固定为func(cCtx *cli.Context)通过fmt.Println把候选词逐行打印到标准输出补全脚本会读取这些输出行并展示给用户。官方注释与示例展示了一个非常重要的防御性写法当已存在位置参数时直接返回if cCtx.NArg() 0 { return }避免在用户已输入参数的情况下继续输出候选造成补全干扰。这也是文档注释 This will complete if no args are passed 的含义。通过cCtx.NArg()/cCtx.Args()等 API你可以根据已输入参数的数量和内容动态决定候选集实现上下文感知的补全。补全回调只在补全模式下被触发由--generate-bash-completionflag 驱动正常执行命令时不会影响Action逻辑。四、启用与持久化把补全装进你的 Shell程序侧写好之后Shell 侧需要加载仓库自带的补全脚本 autocomplete/bash_autocomplete。4.1 当前会话启用脚本通过环境变量PROG获知你的程序名然后source脚本即可$ PROGmyprogram source path/to/cli/autocomplete/bash_autocomplete注意PROG必须与你的程序二进制名称完全一致source的方式只对当前 Shell 会话生效打开新终端后需要重新执行这是快速验证补全效果最直接的方式。4.2 持久化分发到 /etc/bash_completion.d要让补全对所有新开的终端永久生效将脚本复制到系统 bash-completion 目录并重命名为你的程序名$ sudo cp path/to/autocomplete/bash_autocomplete /etc/bash_completion.d/myprogram $ source /etc/bash_completion.d/myprogram官方文档特别提醒文件必须重命名为myprogram去掉bash_autocomplete后缀bash-completion 按文件名关联可补全的程序如果你在分发软件包如 deb/rpm可以考虑在安装脚本中自动完成这一复制动作让用户开箱即用复制后记得source该文件或重启 Shell 才能在当前会话激活。4.3 持久化写入 bash 配置文件如果不便安装到系统目录也可以在用户的~/.bashrc或~/.bash_profile中追加以下两行$ PROGmyprogram $ source path/to/cli/autocomplete/bash_autocomplete这样每次启动新 Shell 都会自动执行 source。4.4 多个程序同时补全需要为多个程序启用补全时必须为每个程序分别设置PROG并 source 一次因为PROG是全局环境变量$ PROGprogram1 $ source path/to/cli/autocomplete/bash_autocomplete $ PROGprogram2 $ source path/to/cli/autocomplete/bash_autocomplete若在同一个 Shell 中只设置一次PROG就 source 多个脚本后设置的脚本会沿用错误的程序名导致补全调用错误的二进制。五、自定义补全触发 flag默认的补全触发 flag 名为--generate-bash-completion其定义暴露为cli.EnableBashCompletion字段v1 中对应cli.BashCompletionFlag见 docs/v1/examples/bash-completions.md。如果它与你的业务 flag 冲突或你想换一个更隐蔽的名字可以重新定义。官方文档给出的重定义示例package main import ( log os github.com/urfave/cli/v2 ) func main() { app : cli.App{ EnableBashCompletion: true, Commands: []*cli.Command{ { Name: wat, }, }, } if err : app.Run(os.Args); err ! nil { log.Fatal(err) } }说明上面这段代码展示的是将触发 flag 隐藏不显示在帮助里后的形态。实际自定义时你可以在设置EnableBashCompletion的同时通过替换触发 flag 定义来改变其名称与可见性例如 v1 示例中的cli.BashCompletionFlag cli.BoolFlag{Name: compgen, Hidden: true}思路v2 中对应字段为cli.EnableBashCompletion所引用的隐藏 flag。注意自定义后补全脚本调用程序的参数也要同步调整。该 flag 是隐藏 flag——它不出现在帮助文本中只被补全脚本内部使用。以文档中的注释块{args: [--generate-bash-completion], output: wat\nhelp\nh}为例直接以该 flag 运行程序时输出即当前可补全的候选词列表子命令 help这正是补全脚本读取的数据源。六、ZSH 与 PowerShell同一套补全能力跨 Shell 复用仓库在 autocomplete 目录下为不同 Shell 提供了开箱即用的脚本官方文档对 zsh 与 PowerShell 给出了完整启用步骤。6.1 ZSH 支持使用仓库内的 autocomplete/zsh_autocomplete启用方式与 bash 完全对称——同样只依赖PROG环境变量在 ZSH 配置文件通常是~/.zshrc中加入$ PROGmyprogram $ source path/to/autocomplete/zsh_autocomplete加入.zshrc后补全即可跨新 Shell 持久生效。脚本内部通过compdef _prog prog注册补全函数并区分当前词以-开头补全 flag/选项与普通词补全子命令两种模式分别调用程序输出候选。6.2 PowerShell 支持使用仓库内的 autocomplete/powershell_autocomplete.ps1将脚本重命名为my program.ps1文件名必须与程序二进制名一致脚本存放位置不限当前会话激活 path/to/autocomplete/my program.ps1跨会话持久化打开 PowerShell profilecode $profile或notepad $profile并追加同一行 path/to/autocomplete/my program.ps16.3 小结各 Shell 启用方式对比Shell脚本文件启用方式持久化方式bashautocomplete/bash_autocompletePROGprog source .../bash_autocomplete复制到/etc/bash_completion.d/prog或写入~/.bashrczshautocomplete/zsh_autocompletePROGprog source .../zsh_autocomplete写入~/.zshrcPowerShellautocomplete/powershell_autocomplete.ps1 path/to/my program.ps1写入 PowerShell profile七、v2 → v3补全 API 的演进对照当前仓库的主模块已是 v3见 go.mod 中module github.com/urfave/cli/v3v3 的补全机制发生了整体重构。官方迁移指南 docs/migrate-v2-to-v3.md 与 v3 文档 docs/v3/examples/completions/shell-completions.md 给出了完整对照7.1 核心字段更名v2本文主体v3cli.App{EnableBashCompletion: true}cli.Command{EnableShellCompletion: true}cli.App{BashComplete: func(ctx *cli.Context){}}cli.Command{ShellComplete: func(ctx context.Context, cmd *cli.Command){}}Commands与Subcommands统一为Commands不再区分层级字段补全触发 flag--generate-bash-completion隐藏 flag--generate-shell-completion定义于 completion.go7.2 启用方式更简化v3 中不再需要手动source仓库脚本只需两步在根Command上设置EnableShellCompletion: true运行greet completion bash之类的内置 completion 子命令动态生成脚本并 source$ greet completion bash $ source (greet completion bash) # 当前会话 $ greet completion bash ~/.bash_completion.d/greet # 持久化新 Shell 自动加载在 v3 的 completion.go 源码中可以看到补全脚本通过embed.FS内嵌//go:embed autocomplete由隐藏的completion子命令支持bash、zsh、fish、pwsh四种 Shell在运行时渲染输出因此分发时不再需要携带任何脚本文件这也是 docs/migrate-v2-to-v3.md 所述Shell completion uses embed.FS for its scripts, with no external dependencies的原因。如果你正在维护 v2 项目可直接沿用本文的EnableBashCompletionBashComplete方案如果新项目起步建议直接采用 v3 的EnableShellCompletion 内置completion子命令方案。八、底层实现速览补全数据从哪来理解机制有助于排查问题。以 v2 的 autocomplete/bash_autocomplete 脚本为例v3 的同名脚本结构与之一致均由 completion.go 内嵌渲染其工作流程是用户按Tabbash 触发__prog_bash_autocomplete函数脚本末尾通过complete -o bashdefault -o default -F __prog_bash_autocomplete prog注册脚本收集光标前的单词数组构造请求若当前词以-开头则追加--generate-shell-completionv2 为--generate-bash-completionflag否则直接附加该 flag脚本eval执行这个带补全 flag 的程序调用程序进入补全模式输出token:description格式的候选行脚本解析输出按冒号切分 token 与描述用compgen -W过滤出与当前输入前缀匹配的候选第二次按TabCOMP_TYPE63即 bash 的补全列表模式时按最宽 token 对齐以token -- description的排版展示带描述的候选列表。v3 的 completion_test.go 与 completion_partial_regression_test.go 对上述流程做了大量断言测试例如校验 bash 脚本中--generate-shell-completion请求格式、描述对齐输出等可作为理解行为边界的参考。九、常见问题与排查思路补全没有生效先确认PROG与程序二进制名完全一致确认source的脚本路径正确确认程序确实以EnableBashCompletion: true编译重新编译后再试。只补全子命令不补全参数参数级补全需要你自行实现BashComplete回调见第三节默认不开启。多个程序补全串扰多个程序需要分别PROGprog source见 4.4不要在同一个环境变量下 source 多个脚本。补全输出乱码或报错检查BashComplete回调是否输出了非候选内容如日志补全候选应只通过fmt.Println输出且输出行遵循token:description格式约定。十、参考资源v2 官方文档docs/v2/examples/bash-completions.md本文主体v1 版本对照docs/v1/examples/bash-completions.mdv3 版本文档docs/v3/examples/completions/shell-completions.md迁移指南docs/migrate-v2-to-v3.md补全脚本autocomplete/bash_autocomplete、autocomplete/zsh_autocomplete、autocomplete/powershell_autocomplete.ps1v3 补全实现与测试completion.go、completion_test.go、completion_partial_regression_test.go赞分享CLI开发工具【免费下载链接】cliA declarative, simple, fast, and fun package for building command line tools in Go项目地址https://gitcode.com/gh_mirrors/cli1/cli点击查看免费下载相关推荐u8views OAuth2集成指南安全连接GitHub账号的最佳实践u8views OAuth2集成指南安全连接GitHub账号的最佳实践 想要安全地追踪GitHub个人主页访问量吗u8views项目提供了完整的OAuth2Ark/Velero CLI 命令详解ark completion 与 Shell 自动补全bash/zsh 实战指南Ark/Velero CLI 命令详解 ark completion 与 Shell 自动补全bash/zsh 实战指南 导读 本指南围绕 Velero云原生灾备存储后端LocalAI 命令行 Shell 补全实战指南为 bash/zsh/fish 启用 tab 自动补全及底层实现解析LocalAI 命令行 Shell 补全实战指南为 bash/zsh/fish 启用 tab 自动补全及底层实现解析 本文档对应的原版参考文档位于 docs/人工智能大模型模型推理服务本地部署LLM 网关AI AgentRAG后端上一篇10分钟打通小米生态JustAuth实现账号与IoT设备统一授权下一篇从崩溃到流畅uWebSockets压缩扩展错误全解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考