py-cli

name	py-cli
description	Build and review robust Python command-line applications with argparse, Typer, Click, Rich, or Textual. Use for commands, subcommands, options, config precedence, environment variables, stdin/stdout/stderr contracts, exit codes, JSON output, progress, shell completion, non-interactive automation, atomic file operations, packaging entry points, and CLI testing across Windows, macOS, and Linux.
compatibility	Agent Skills-compatible. Framework APIs vary by version; inspect the lockfile and preserve existing command contracts before refactoring.
metadata	{"author":"stevenke1981","version":"2.0.0","last-reviewed":"2026-07-30"}

Python CLI 應用工程

目標與邊界

用此 skill 建立對人友善、對 script 穩定、可在 CI 非互動執行的命令列工具。CLI 是公開 API：command、option、exit code、stdout 格式與設定優先序都需要相容性管理。

若需求是桌面視窗，使用 py-gui；若只是 library 內部函式，不要為了展示而建立多餘 CLI。

執行流程

1. 定義命令契約：command/subcommand、參數、option、stdin、stdout、stderr、exit code 與副作用。
2. 辨識使用者：互動式人類、shell script、CI、排程、容器或遠端執行。
3. 選擇框架：依複雜度、既有依賴、型別與 plugin 需求決定 argparse、Typer、Click 或 Textual。
4. 定義設定優先序：CLI > environment > config file > defaults，並提供來源可觀測性。
5. 分離核心邏輯：command function 只解析、呼叫 service、格式化結果與轉換錯誤。
6. 設計安全副作用：dry-run、確認、atomic write、idempotency 與 path validation。
7. 支援自動化：--json、--no-input、穩定 exit code、禁用顏色/動畫與可預測輸出。
8. 測試與打包：CliRunner/subprocess、entry point、Windows 路徑與 shell completion。

框架選擇

需求	優先方案
零第三方依賴、標準庫工具	argparse
型別提示、快速開發、Rich 整合	Typer
大型成熟 CLI、plugin、細緻 context	Click
終端機全螢幕互動 UI	Textual
少數固定參數	不需要額外 framework

不要在既有 Click/Typer 專案中無理由切換框架；command contract 的穩定性比框架偏好重要。

CLI 輸出契約

stdout

• 只輸出主要結果或可供 pipe 的資料。
• --json 輸出單一有效 JSON document 或明確 JSON Lines。
• machine-readable 模式不得混入 spinner、banner、warning 或 debug log。

stderr

• 診斷、warning、progress 與錯誤訊息。
• 敏感參數必須遮蔽。
• 非 TTY 時停用動態 repaint 與 ANSI color，除非使用者明確要求。

exit code

建議穩定分類並寫入文件：

Code	意義
0	成功
1	一般執行失敗
2	使用方式或驗證錯誤
3	找不到資源／設定
4	權限或認證失敗
5	暫時性外部服務失敗
130	使用者中斷（常見 shell 慣例）

不要把所有失敗都轉成 0，也不要讓 stack trace 成為一般使用者唯一訊息。

Typer 結構範例

from __future__ import annotations

import json
from dataclasses import dataclass
from pathlib import Path
from typing import Annotated

import typer


app = typer.Typer(no_args_is_help=True)


@dataclass(frozen=True, slots=True)
class AppContext:
    config_path: Path | None
    json_output: bool


@app.callback()
def main(
    ctx: typer.Context,
    config: Annotated[
        Path | None,
        typer.Option("--config", exists=True, dir_okay=False, readable=True),
    ] = None,
    json_output: Annotated[
        bool,
        typer.Option("--json", help="Emit machine-readable JSON."),
    ] = False,
) -> None:
    ctx.obj = AppContext(config_path=config, json_output=json_output)


@app.command()
def greet(
    ctx: typer.Context,
    name: Annotated[str, typer.Argument(help="Name to greet.")],
) -> None:
    settings = ctx.find_object(AppContext)
    if settings is None:
         RuntimeError()

    payload = {: }
     settings.json_output:
        typer.echo(json.dumps(payload, ensure_ascii=))
    :
        typer.echo(payload[])


 __name__ == :
    app()

避免用 module-level mutable dict 保存 command 狀態。context、service 或 immutable settings 應由 callback/組合根建立並注入。

argparse 結構

對小型零依賴工具：

import argparse
from collections.abc import Sequence


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(prog="example-tool")
    parser.add_argument("path")
    parser.add_argument("--json", action="store_true", dest="json_output")
    return parser


def main(argv: Sequence[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    try:
        run(path=args.path, json_output=args.json_output)
    except FileNotFoundError as exc:
        print(f"error: {exc}", file=sys.stderr)
        return 3
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

實際程式需 import sys；將 argv 注入可讓 unit test 不必 patch 全域 sys.argv。

設定優先序

固定規則：

command-line option
  > environment variable
  > project/user config file
  > application default

• 每個 setting 只在一個地方 resolve。
• --show-config 可顯示非敏感 effective settings 與來源。
• config path 使用 pathlib 與 platform-appropriate user config directory。
• 不自動讀取目前目錄中的未知設定檔，除非文件明確說明，避免不可信專案影響執行。
• API key 不寫入一般明文 config；優先 environment、OS credential store 或 secret manager。

非互動與 CI

提供：

• --no-input 或明確 --yes
• --json / --format
• --quiet / --verbose
• timeout、retry 與 concurrency options
• --dry-run 對寫入、刪除、部署、發信等副作用
• stable exit codes
• environment 變數對應

規則：

• stdin 不是 TTY 時不要突然 prompt。
• --yes 只能略過已文件化確認，不能放寬權限或 validation。
• CI 中 progress bar 不得汙染 machine output。
• secret 不可出現在 process title、shell history 或 command echo；必要時從 stdin/file descriptor/secret store 讀取。

Path 與檔案操作

• 使用 Path，但不要假設路徑分隔符與大小寫規則。
• 接收 input path 時檢查 exists/type/readability。
• output 避免覆蓋，除非 --force 或明確策略。
• 寫檔使用同目錄 temporary file + flush/fsync（依需求）+ atomic replace。
• archive extraction 防 path traversal、symlink 與 decompression bomb。
• - 可作 stdin/stdout 時，清楚區分 text 與 binary mode。

錯誤處理

command boundary 將 domain error 映射為 CLI error：

class UserFacingError(Exception):
    def __init__(self, message: str, *, exit_code: int = 1) -> None:
        super().__init__(message)
        self.exit_code = exit_code


def render_failure(exc: UserFacingError, *, debug: bool) -> None:
    typer.echo(f"error: {exc}", err=True)
    if debug:
        raise exc
    raise typer.Exit(exc.exit_code)

• 預期錯誤顯示短訊息與修正方式。
• --debug 才顯示 traceback。
• 不捕捉 BaseException；保留 KeyboardInterrupt/SystemExit 語意。
• 使用者中斷時清理資源並回傳適當 exit code。
• partial success 要有明確 summary 與非零/零政策。

Progress 與 Rich

• 只有 TTY 且非 JSON/quiet 模式才顯示動態 progress。
• progress total 不確定時使用 spinner，但仍顯示目前階段。
• log 與 progress 避免互相覆蓋。
• 支援 NO_COLOR 或 framework 等效設定。
• screen reader/redirect 情境提供純文字模式。

Plugin 與 Subcommand

• 大型 CLI 可用 entry points 發現 plugin。
• plugin API 需版本化、隔離 import error 並可列出停用原因。
• 不在 --help 時載入大型模型、網路 client 或所有 plugin 副作用。
• subcommand 名稱與 option 一旦發布即視為相容契約。
• deprecated option 提供 warning、替代方式與移除版本。

測試策略

Typer/Click Runner

from typer.testing import CliRunner


runner = CliRunner()


def test_greet_json() -> None:
    result = runner.invoke(app, ["--json", "greet", "Ada"])
    assert result.exit_code == 0
    assert json.loads(result.stdout) == {"message": "Hello, Ada!"}

測試還應涵蓋：

• --help 與 no-args behavior
• invalid argument 與 exit code
• stdout/stderr 分離
• JSON 可解析且無額外文字
• config precedence
• no-input / TTY 差異
• temp directory、atomic write 與 --force
• Ctrl-C、timeout 與 partial failure
• entry point 安裝後用 subprocess smoke test
• Windows quoting/path、macOS/Linux permission

打包與 Entry Point

[project.scripts]
example-tool = "example_tool.cli:app"

依框架確認 target 是 callable/app。建 wheel 後在乾淨 venv 測：

example-tool --help
example-tool --version

不要只用 python -m package.cli 測試而忽略安裝 entry point。

交付標準

• command、option、stdin/stdout/stderr 與 exit code 契約已文件化。
• 核心邏輯與 CLI framework 分離，可直接 unit test。
• 設定優先序固定，effective config 可檢查且不洩漏秘密。
• 非互動模式無 prompt、動畫或混雜 machine output。
• 副作用有 dry-run、確認、atomic write 與可回復策略。
• 錯誤映射穩定，一般模式不輸出無用 traceback。
• Windows、macOS、Linux 的 path/encoding/entry point 已測。
• wheel 安裝後的實際 command 已 smoke test。

延伸閱讀

• 完整範例
• 速查表
• 常見陷阱

版本相容性

環境	建議
Python 3.14	穩定維護基準
Python 3.10–3.13	支援；依專案最低版本調整 typing 語法
Typer/Click/Rich	依 lockfile 與官方文件驗證 context、testing 與 output API
Windows/macOS/Linux	每個平台執行 entry point smoke test
Preview Python	只作 compatibility job，不作唯一發布環境