unix-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UNIX/POSIX Standards CLI Best Practices

UNIX/POSIX标准CLI最佳实践

Comprehensive guidelines for building command-line tools that follow UNIX conventions, designed for AI agents and LLMs. Contains 44 rules across 8 categories, prioritized by impact from critical (argument handling, exit codes, output streams) to incremental (configuration and environment).

这是为AI Agent和LLM打造的、构建遵循UNIX规范的命令行工具的综合指南。包含8个类别共44条规则，按影响程度从关键级别（参数处理、退出码、输出流）到增量级别（配置与环境）排序。

When to Apply

适用场景

Reference these guidelines when:

Writing new CLI tools in any language
Parsing command-line arguments and flags
Deciding what goes to stdout vs stderr
Choosing appropriate exit codes
Handling signals like SIGINT and SIGTERM

在以下场景中参考本指南：

用任意语言编写新的CLI工具
解析命令行参数与标志
决定输出内容发送到stdout还是stderr
选择合适的退出码
处理SIGINT和SIGTERM等信号

Rule Categories by Priority

按优先级划分的规则类别


args-
exit-
output-
error-
io-
help-
signal-
config-

Priority	Category	Impact	Prefix
1	Argument & Flag Design	CRITICAL	`args-`
2	Exit Codes	CRITICAL	`exit-`
3	Output Streams	CRITICAL	`output-`
4	Error Handling	HIGH	`error-`
5	I/O & Composition	HIGH	`io-`
6	Help & Documentation	MEDIUM-HIGH	`help-`
7	Signals & Robustness	MEDIUM	`signal-`
8	Configuration & Environment	MEDIUM	`config-`


args-
exit-
output-
error-
io-
help-
signal-
config-

优先级	类别	影响程度	前缀
1	参数与标志设计	关键	`args-`
2	退出码	关键	`exit-`
3	输出流	关键	`output-`
4	错误处理	高	`error-`
5	I/O与组合	高	`io-`
6	帮助与文档	中高	`help-`
7	信号与健壮性	中	`signal-`
8	配置与环境	中	`config-`

Quick Reference

快速参考

1. Argument & Flag Design (CRITICAL)

1. 参数与标志设计（关键）

```
args-use-getopt
```
- Use standard argument parsing libraries
```
args-provide-long-options
```
- Provide long options for all short options
```
args-support-double-dash
```
- Support double-dash to terminate options
```
args-require-help-version
```
- Implement --help and --version options
```
args-prefer-flags-over-positional
```
- Prefer flags over positional arguments
```
args-use-standard-flag-names
```
- Use standard flag names
```
args-never-read-secrets-from-flags
```
- Never read secrets from command-line flags
```
args-support-option-bundling
```
- Support option bundling

```
args-use-getopt
```
- 使用标准参数解析库
```
args-provide-long-options
```
- 为所有短选项提供长选项
```
args-support-double-dash
```
- 支持双短横线来终止选项解析
```
args-require-help-version
```
- 实现--help和--version选项
```
args-prefer-flags-over-positional
```
- 优先使用标志而非位置参数
```
args-use-standard-flag-names
```
- 使用标准标志名称
```
args-never-read-secrets-from-flags
```
- 绝不从命令行标志中读取敏感信息
```
args-support-option-bundling
```
- 支持选项捆绑

2. Exit Codes (CRITICAL)

2. 退出码（关键）

```
exit-zero-for-success
```
- Return zero for success only
```
exit-use-standard-codes
```
- Use standard exit codes
```
exit-signal-codes
```
- Use 128+N for signal termination
```
exit-partial-success
```
- Handle partial success consistently
```
exit-distinguish-error-types
```
- Distinguish error types with different exit codes

```
exit-zero-for-success
```
- 仅在成功时返回0
```
exit-use-standard-codes
```
- 使用标准退出码
```
exit-signal-codes
```
- 信号终止时使用128+N作为退出码
```
exit-partial-success
```
- 一致处理部分成功的场景
```
exit-distinguish-error-types
```
- 用不同退出码区分错误类型

3. Output Streams (CRITICAL)

3. 输出流（关键）

```
output-stdout-for-data
```
- Write data to stdout only
```
output-stderr-for-errors
```
- Write errors and diagnostics to stderr
```
output-detect-tty
```
- Detect TTY for human-oriented output
```
output-provide-machine-format
```
- Provide machine-readable output format
```
output-line-based-text
```
- Use line-based output for text streams
```
output-respect-no-color
```
- Respect NO_COLOR environment variable

```
output-stdout-for-data
```
- 仅将数据写入stdout
```
output-stderr-for-errors
```
- 将错误与诊断信息写入stderr
```
output-detect-tty
```
- 检测TTY以输出面向人类的内容
```
output-provide-machine-format
```
- 提供机器可读的输出格式
```
output-line-based-text
```
- 文本流使用基于行的输出
```
output-respect-no-color
```
- 遵循NO_COLOR环境变量设置

4. Error Handling (HIGH)

4. 错误处理（高）

```
error-include-program-name
```
- Include program name in error messages
```
error-actionable-messages
```
- Make error messages actionable
```
error-use-strerror
```
- Use strerror for system errors
```
error-avoid-stack-traces
```
- Avoid stack traces in user-facing errors
```
error-validate-early
```
- Validate input early and fail fast

```
error-include-program-name
```
- 错误消息中包含程序名称
```
error-actionable-messages
```
- 使错误消息具备可操作性
```
error-use-strerror
```
- 系统错误使用strerror输出
```
error-avoid-stack-traces
```
- 面向用户的错误中避免显示堆栈跟踪
```
error-validate-early
```
- 尽早验证输入并快速失败

5. I/O & Composition (HIGH)

5. I/O与组合（高）

```
io-support-stdin
```
- Support reading from stdin
```
io-write-to-stdout
```
- Write output to stdout by default
```
io-be-stateless
```
- Design stateless operations
```
io-handle-binary-safely
```
- Handle binary data safely
```
io-atomic-writes
```
- Use atomic file writes
```
io-handle-multiple-files
```
- Handle multiple input files consistently

```
io-support-stdin
```
- 支持从stdin读取内容
```
io-write-to-stdout
```
- 默认将输出写入stdout
```
io-be-stateless
```
- 设计无状态操作
```
io-handle-binary-safely
```
- 安全处理二进制数据
```
io-atomic-writes
```
- 使用原子文件写入
```
io-handle-multiple-files
```
- 一致处理多个输入文件

6. Help & Documentation (MEDIUM-HIGH)

6. 帮助与文档（中高）

```
help-show-usage-on-error
```
- Show brief usage on argument errors
```
help-structure-help-output
```
- Structure help output consistently
```
help-show-defaults
```
- Show default values in help
```
help-include-examples
```
- Include practical examples in help
```
help-version-format
```
- Format version output correctly

```
help-show-usage-on-error
```
- 参数错误时显示简要用法
```
help-structure-help-output
```
- 一致组织帮助输出结构
```
help-show-defaults
```
- 帮助中显示默认值
```
help-include-examples
```
- 帮助中包含实用示例
```
help-version-format
```
- 正确格式化版本输出

7. Signals & Robustness (MEDIUM)

7. 信号与健壮性（中）

```
signal-handle-sigint
```
- Handle SIGINT gracefully
```
signal-handle-sigterm
```
- Handle SIGTERM for clean shutdown
```
signal-handle-sigpipe
```
- Handle SIGPIPE for broken pipes
```
signal-cleanup-on-second-interrupt
```
- Skip cleanup on second interrupt

```
signal-handle-sigint
```
- 优雅处理SIGINT信号
```
signal-handle-sigterm
```
- 处理SIGTERM以实现干净关闭
```
signal-handle-sigpipe
```
- 处理SIGPIPE以应对管道断裂
```
signal-cleanup-on-second-interrupt
```
- 第二次中断时跳过清理操作

8. Configuration & Environment (MEDIUM)

8. 配置与环境（中）

```
config-follow-xdg
```
- Follow XDG Base Directory Specification
```
config-precedence-order
```
- Apply configuration in correct precedence order
```
config-env-naming
```
- Use consistent environment variable naming
```
config-never-store-secrets
```
- Never store secrets in config files or environment
```
config-respect-standard-vars
```
- Respect standard environment variables

```
config-follow-xdg
```
- 遵循XDG基础目录规范
```
config-precedence-order
```
- 按正确的优先级顺序应用配置
```
config-env-naming
```
- 使用一致的环境变量命名规则
```
config-never-store-secrets
```
- 绝不将敏感信息存储在配置文件或环境变量中
```
config-respect-standard-vars
```
- 遵循标准环境变量设置

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件获取详细说明和代码示例：

章节定义 - 类别结构与影响级别
规则模板 - 添加新规则的模板

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
references/_sections.md	类别定义与排序
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息