Back to Details

cli-building

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CLI Building

CLI 构建

Guidelines for building command-line interfaces with modern patterns and best practices.
采用现代模式与最佳实践构建命令行界面的指南。

When to Use

适用场景

  • Creating new CLI tools or commands
  • Building interactive terminal applications
  • Adding commands to existing projects
  • Implementing command-line interfaces
  • Working with CLI frameworks
  • 创建新的CLI工具或命令
  • 构建交互式终端应用程序
  • 为现有项目添加命令
  • 实现命令行界面
  • 使用CLI框架进行开发

Core Principles

核心原则

  • Async-first: All I/O operations should be async/await, avoid blocking operations
  • Composable commands: Commands should be modular and reusable, use command composition
  • Strategy pattern: Use strategy pattern for branching workflows or task-based commands
  • Output formatting: Proper formatting with unicode symbols and color support
  • 异步优先：所有I/O操作均应使用async/await，避免阻塞操作
  • 可组合命令：命令应具备模块化和可复用性，采用命令组合方式
  • 策略模式：针对分支工作流或基于任务的命令使用策略模式
  • 输出格式：使用Unicode符号和颜色支持实现规范的格式

Framework Selection

框架选择

TypeScript/JavaScript

TypeScript/JavaScript

stricli (
@bloomberg/stricli
, recommended for modern async-first CLIs):
  • Built for async/await from ground up
  • Type-safe command definitions with full type inference
  • Lazy loading for startup performance
  • Zero dependencies
oclif (alternative):
  • Mature framework with extensive features
  • Plugin system
  • Good for complex CLIs
stricli（
@bloomberg/stricli
，推荐用于现代异步优先CLI）:
  • 从底层为async/await构建
  • 具备完整类型推断的类型安全命令定义
  • 延迟加载以提升启动性能
  • 零依赖
oclif（替代方案）:
  • 功能丰富的成熟框架
  • 插件系统
  • 适用于复杂CLI

Python

Python

cyclopts (recommended for async-first):
  • Modern async-first CLI framework
  • Type-safe with excellent async support
  • Clean API design
typer (when fully async support available):
  • Based on Python type hints
  • Clean and intuitive
  • Good for simple to medium complexity CLIs
cyclopts（推荐用于异步优先场景）:
  • 现代异步优先CLI框架
  • 类型安全且具备出色的异步支持
  • 简洁的API设计
typer（当需要完整异步支持时）:
  • 基于Python类型提示
  • 简洁直观
  • 适用于简单到中等复杂度的CLI

Command Architecture

命令架构

Composable Commands

可组合命令

Design commands as reusable modules:
  • Shared command utilities
  • Command middleware
  • Reusable command modules
  • Command composition patterns
将命令设计为可复用模块：
  • 共享命令工具
  • 命令中间件
  • 可复用命令模块
  • 命令组合模式

Strategy Pattern

策略模式

Use strategy pattern for:
  • Workflow branching
  • Task-based commands
  • Dynamic command routing
  • Conditional command execution
策略模式适用于：
  • 工作流分支
  • 基于任务的命令
  • 动态命令路由
  • 条件命令执行

Output Formatting

输出格式

  • No emojis: Do not use emojis unless explicitly directed
  • Unicode symbols: Use unicode symbols (✓, ✗, →, ⚠) for status indicators
  • Color support: Use color libraries, never hardcoded ANSI codes
  • NO_COLOR: Always respect 
    NO_COLOR
    environment variable
  • Formatting: Use formatting for better readability (bold, dim, etc.)
  • 禁止使用表情符号：除非明确要求，否则不要使用表情符号
  • Unicode符号：使用Unicode符号（✓, ✗, →, ⚠）作为状态指示器
  • 颜色支持：使用颜色库，切勿硬编码ANSI代码
  • NO_COLOR：始终遵循
    NO_COLOR
    环境变量
  • 格式设置：使用格式设置提升可读性（加粗、变暗等）

Async Patterns

异步模式

Async-First Design

异步优先设计

All I/O should be async:
  • File operations: use async file APIs
  • Network requests: use async HTTP clients
  • Process execution: use async process APIs
  • Database operations: use async database clients
所有I/O操作均应采用异步方式：
  • 文件操作：使用异步文件API
  • 网络请求：使用异步HTTP客户端
  • 进程执行：使用异步进程API
  • 数据库操作：使用异步数据库客户端

Error Handling

错误处理

Handle async errors properly:
  • Use try/catch with await
  • Handle promise rejections
  • Provide clear error messages
  • Exit with appropriate codes
正确处理异步错误：
  • 结合await使用try/catch
  • 处理Promise拒绝
  • 提供清晰的错误消息
  • 使用适当的退出码退出

Command Structure

命令结构

Basic Command

基础命令

typescript
// stricli example
import { createCli } from '@bloomberg/stricli';

async function myCommand() {
  // Async implementation
}

const cli = createCli({
  name: 'my-cli',
  commands: {
    'my-command': myCommand
  }
});

cli.run();
python
undefined
typescript
// stricli example
import { createCli } from '@bloomberg/stricli';

async function myCommand() {
  // Async implementation
}

const cli = createCli({
  name: 'my-cli',
  commands: {
    'my-command': myCommand
  }
});

cli.run();
python
undefined

cyclopts example

cyclopts example

from cyclopts import App
app = App()
@app.default async def my_command(): # Async implementation pass
if name == 'main': app()
undefined
from cyclopts import App
app = App()
@app.default async def my_command(): // Async implementation pass
if name == 'main': app()
undefined

Best Practices

最佳实践

  1. Async by default: All operations should be async
  2. Composable design: Build reusable command modules
  3. Strategy pattern: Use for workflow branching
  4. Proper formatting: Unicode symbols and color with NO_COLOR support
  5. Error handling: Clear error messages and exit codes
  6. Type safety: Use TypeScript types or Python type hints
  7. Testing: Test commands in isolation
  1. 默认异步：所有操作均应采用异步方式
  2. 可组合设计：构建可复用的命令模块
  3. 策略模式：用于工作流分支
  4. 规范格式：使用Unicode符号和颜色并支持NO_COLOR
  5. 错误处理：提供清晰的错误消息和退出码
  6. 类型安全：使用TypeScript类型或Python类型提示
  7. 测试：独立测试命令

References

参考资料

For detailed guidance, see:
  • references/async-patterns.md
    - Async/await best practices
  • references/composable-commands.md
    - Command composition patterns
  • references/strategy-pattern.md
    - Strategy pattern for workflows
  • references/output-formatting.md
    - Output formatting guidelines
  • references/frameworks.md
    - Framework comparisons and selection
如需详细指导，请参阅：
  • references/async-patterns.md
    - Async/await最佳实践
  • references/composable-commands.md
    - 命令组合模式
  • references/strategy-pattern.md
    - 工作流策略模式
  • references/output-formatting.md
    - 输出格式指南
  • references/frameworks.md
    - 框架对比与选择