CLI构建Skill building-clis

---

name: 构建命令行界面 description: 使用现代框架如Typer、Cobra和clap在Python、Go和Rust中构建专业的命令行界面。适用于创建开发工具、自动化脚本或基础设施管理CLI，具有强大的参数解析、交互功能和跨平台分发能力。

构建命令行界面

使用现代框架在Python、Go和Rust中构建专业的命令行界面，具有强大的参数解析、配置管理和shell集成功能。

何时使用此技能

在以下情况使用此技能：

• 构建开发工具或自动化CLI
• 创建基础设施管理工具（部署、监控）
• 实现API客户端命令行工具
• 为现有项目添加CLI功能
• 打包实用程序以分发（PyPI、Homebrew、二进制发布）

常见触发词：“创建一个CLI工具”、“构建一个命令行界面”、“添加CLI参数”、“解析命令行选项”、“生成shell补全”

框架选择

快速决策指南

Python项目：

• Typer（推荐）：具有最小模板的现代类型安全CLI
• Click：成熟、灵活的CLI，适用于复杂命令层次结构

Go项目：

• Cobra（推荐）：企业工具（如Kubernetes、Docker、GitHub CLI）的行业标准
• urfave/cli：轻量级替代方案，适用于简单CLI

Rust项目：

• clap v4（推荐）：类型安全，使用derive API或builder API实现运行时灵活性

有关详细的框架比较和选择标准，请参阅references/framework-selection.md。

核心模式

参数 vs. 选项 vs. 标志

位置参数：

• 主要输入，通过位置识别
• 用于必需输入（最多2-3个参数）
• 示例：convert input.jpg output.png

选项：

• 带值的命名参数
• 用于配置和可选输入
• 示例：--output file.txt、--config app.yaml

标志：

• 布尔选项（存在即真）
• 用于开关和切换
• 示例：--verbose、--dry-run、--force

决策矩阵：

用例	类型	示例
主要必需输入	位置参数	git commit -m "message"
可选配置	选项	--config app.yaml
布尔设置	标志	--verbose、--force
多个值	可变参数	files...

有关全面的解析模式，请参阅references/argument-patterns.md。

子命令组织

扁平结构（1级）：

app command1 [args]
app command2 [args]

适用于：具有5-10个操作的小型CLI

分组结构（2级）：

app group subcommand [args]

适用于：具有逻辑分组的中型CLI（10-30个命令） 示例：kubectl get pods、kubectl create deployment

嵌套结构（3+级）：

app group subgroup command [args]

适用于：具有深层层次结构的大型CLI（30+个命令） 示例：gcloud compute instances create

有关结构策略，请参阅references/subcommand-design.md。

配置管理

标准优先级（从高到低）：

1. CLI参数/标志（明确的用户输入）
2. 环境变量（会话覆盖）
3. 配置文件 - 本地（./config.yaml）
4. 配置文件 - 用户（~/.config/app/config.yaml）
5. 配置文件 - 系统（/etc/app/config.yaml）
6. 内置默认值（硬编码）

最佳实践：

• 在--help中记录优先级
• 执行前验证配置文件
• 提供--print-config以显示有效配置
• 使用XDG基础目录（~/.config/app/）存储配置文件

有关跨语言实现模式，请参阅references/configuration-management.md。

输出格式化

格式选择：

用例	格式	何时使用
人类消费	彩色文本、表格	默认交互模式
机器消费	JSON、YAML	--output json、管道传输
日志/调试	纯文本	--verbose、stderr
进度跟踪	进度条、旋转器	长时间操作

最佳实践：

• 默认以人类可读输出
• 提供--output标志（json、yaml、table）
• 使用stderr记录日志，stdout输出数据
• 自动检测TTY（非交互时禁用颜色）
• 使用退出码：0 = 成功，1 = 错误，2 = 用法错误

有关格式化策略，请参阅references/output-formatting.md。

语言特定快速入门

Python with Typer

安装：

pip install "typer[all]"  # 包含rich以支持彩色输出

基本示例：

import typer
from typing import Annotated

app = typer.Typer()

@app.command()
def greet(
    name: Annotated[str, typer.Argument(help="要问候的名称")],
    formal: Annotated[bool, typer.Option(help="使用正式问候")] = False
):
    """用消息问候某人。"""
    greeting = "Good day" if formal else "Hello"
    typer.echo(f"{greeting}, {name}!")

if __name__ == "__main__":
    app()

关键功能：

• 类型提示用于自动验证
• 装饰器实现最小模板
• 自动生成的帮助文本
• 集成rich以支持彩色输出

有关完整的工作示例，包括子命令、配置管理和交互功能，请参阅examples/python/。

Go with Cobra

安装：

go get -u github.com/spf13/cobra@latest

基本示例：

var rootCmd = &cobra.Command{
    Use:   "greet [name]",
    Args:  cobra.ExactArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Printf("Hello, %s!
", args[0])
    },
}

rootCmd.Flags().Bool("formal", false, "使用正式问候")
rootCmd.Execute()

关键功能：

• POSIX兼容的标志
• Viper集成以支持配置
• 子命令架构
• shell补全生成

有关完整的工作示例，包括Viper配置和多级子命令，请参阅examples/go/。

Rust with clap

安装（Cargo.toml）：

[dependencies]
clap = { version = "4.5", features = ["derive"] }

基本示例（Derive API）：

use clap::Parser;

#[derive(Parser)]
#[command(about = "问候某人")]
struct Cli {
    /// 要问候的名称
    name: String,

    /// 使用正式问候
    #[arg(long)]
    formal: bool,
}

fn main() {
    let cli = Cli::parse();
    let greeting = if cli.formal { "Good day" } else { "Hello" };
    println!("{}, {}!", greeting, cli.name);
}

关键功能：

• 编译时类型安全
• Derive API（声明式）或Builder API（程序式）
• 全面验证
• 性能优化

有关完整的工作示例，包括子命令和builder API模式，请参阅examples/rust/。

交互功能

进度指示器

Python（rich）：

from rich.progress import track
for _ in track(range(100), description="处理中..."):
    time.sleep(0.01)

Go（progressbar）：

import "github.com/schollz/progressbar/v3"
bar := progressbar.Default(100)
for i := 0; i < 100; i++ {
    bar.Add(1)
}

Rust（indicatif）：

use indicatif::ProgressBar;
let bar = ProgressBar::new(100);
for _ in 0..100 {
    bar.inc(1);
}

提示和确认

Python：

confirm = typer.confirm("确定吗？")
if not confirm:
    raise typer.Abort()

Go：

reader := bufio.NewReader(os.Stdin)
fmt.Print("确定吗？（y/n）：")
response, _ := reader.ReadString('
')

Rust：

use dialoguer::Confirm;
if Confirm::new().with_prompt("确定吗？").interact()? {
    // 继续
}

Shell补全

生成补全

Python（Typer）：

_MYAPP_COMPLETE=bash_source myapp > ~/.myapp-complete.bash
_MYAPP_COMPLETE=zsh_source myapp > ~/.myapp-complete.zsh

Go（Cobra）：

rootCmd.AddCommand(&cobra.Command{
    Use:   "completion [bash|zsh|fish|powershell]",
    Args:  cobra.ExactArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
        switch args[0] {
        case "bash":
            rootCmd.GenBashCompletion(os.Stdout)
        case "zsh":
            rootCmd.GenZshCompletion(os.Stdout)
        }
    },
})

Rust（clap）：

use clap_complete::{generate, shells::Bash};
generate(Bash, &mut Cli::command(), "myapp", &mut io::stdout())

有关安装说明，请参阅references/shell-completion.md。

分发和打包

Python（PyPI）

pyproject.toml：

[project]
name = "myapp"
version = "1.0.0"
scripts = { myapp = "myapp.cli:app" }

发布：

pip install build twine
python -m build
twine upload dist/*

Go（Homebrew）

公式：

class Myapp < Formula
  desc "我的CLI应用"
  url "https://github.com/user/myapp/archive/v1.0.0.tar.gz"

  def install
    system "go", "build", "-o", bin/"myapp"
  end
end

Rust（Cargo）

发布：

cargo login
cargo publish

安装：

cargo install myapp

有关全面的打包策略，包括二进制发布，请参阅references/distribution.md。

最佳实践

通用CLI约定

始终提供：

• --help和-h以获取使用信息
• --version和-V以显示版本
• 清晰错误消息和可操作建议

参数处理：

• 使用--分隔符区分选项和位置参数
• 支持短形式（-v）和长形式（--verbose）
• 验证和清理所有用户输入

错误处理：

• 退出码0表示成功
• 退出码1表示一般错误
• 退出码2表示用法错误
• 错误写入stderr，数据写入stdout

交互性：

• 检测TTY（交互式 vs. 管道输入）
• 提供--yes/--force以跳过自动化提示
• 显示超过2秒操作的进度

配置最佳实践

文件格式：

• 一致使用YAML、TOML或JSON
• 按环境（开发、测试、生产）分隔文件
• 在CI/CD中使用--check-config验证配置

秘密管理：

• 切勿将秘密提交到配置文件
• 使用环境变量或秘密管理器
• 记录必需的环境变量

优先级：

• CLI参数 > 环境变量 > 配置文件 > 默认值
• 在帮助文本中记录优先级
• 提供--print-config以显示有效配置

与其他技能集成

testing-strategies：

• 使用模拟和固定装置进行CLI测试
• 端到端工作流的集成测试
• 请参阅examples/python/test_cli.py

building-ci-pipelines：

• 多平台二进制构建
• 通过GitHub Actions自动化发布
• 请参阅references/distribution.md

api-patterns：

• 构建API客户端CLI
• 认证和令牌管理
• 格式化API响应

secret-management：

• 安全凭证存储
• 环境变量集成
• Vault/秘密管理器集成

参考文件

决策框架：

• framework-selection.md - 选择哪个框架
• argument-patterns.md - 参数 vs. 选项 vs. 标志
• subcommand-design.md - 命令层次结构设计

实现指南：

• configuration-management.md - 配置文件和优先级
• output-formatting.md - 人类 vs. 机器可读输出
• shell-completion.md - 生成补全
• distribution.md - 打包和发布CLI

代码示例：

• examples/python/ - Typer示例（基本、子命令、配置、交互）
• examples/go/ - Cobra示例（基本、子命令、Viper集成）
• examples/rust/ - clap示例（derive、builder、子命令）

快速参考

框架推荐：

• Python：Typer（现代）或Click（成熟）
• Go：Cobra（企业级）或urfave/cli（简单）
• Rust：clap v4（derive或builder）

常见模式：

• 参数：主要输入（最多2-3个）
• 选项：带值的命名参数
• 标志：布尔开关
• 子命令：分组相关操作
• 配置：CLI参数 > 环境变量 > 文件 > 默认值

输出标准：

• 默认：人类可读（彩色、表格）
• 机器：通过--output标志的JSON/YAML
• 错误：stderr，数据：stdout
• 退出：0 = 成功，1 = 错误，2 = 用法

分发：

• Python：PyPI（pip install）
• Go：Homebrew、二进制发布
• Rust：Cargo（cargo install）、二进制发布