cli-patterns

注意: 実装前に context7 MCP で typer/rich API の詳細を確認してください。

コマンド構造 (typer)

import typer
from rich.console import Console

app = typer.Typer(help="My CLI Tool", no_args_is_help=True)
console = Console(stderr=True)  # UI on stderr, data on stdout

@app.command()
def generate(
    input_file: str = typer.Argument(help="Input file path"),
    prompt: str = typer.Argument(help="Generation prompt"),
    provider: str = typer.Option(None, "--provider", "-p",
        help="LLM provider (e.g., ollama/qwen3:4b-instruct)"),
    verbose: int = typer.Option(0, "--verbose", "-v", count=True,
        help="Increase verbosity (-v, -vv, -vvv)"),
    json_output: bool = typer.Option(False, "--json",
        help="Output as JSON (for scripting)"),
):
    """Generate output using the configured LLM pipeline."""

出力の原則

• stdout = データ (パイプ可能)。stderr = UI (進捗、ステータス、エラー)。
• すべてのリッチ出力に Console(stderr=True) を使用します。
• マシン可読な出力として --json をサポートします。
• 終了コード: 0=成功、1=ユーザーエラー、2=システムエラー。

冗長性レベル

import structlog
log = structlog.get_logger()

# Map -v flags to log levels
LOG_LEVELS = {0: "WARNING", 1: "INFO", 2: "DEBUG", 3: "DEBUG"}  # -vvv = trace via structlog

def configure_logging(verbose: int):
    level = LOG_LEVELS.get(min(verbose, 3), "DEBUG")
    structlog.configure(wrapper_class=structlog.make_filtering_bound_logger(level))

フラグ	表示内容	用途
(なし)	結果のサマリー	通常の使用
-v	ステージ遷移、主要な判定	フロー理解
-vv	API呼び出し、タイミング、トークン	パフォーマンスデバッグ
-vvv	完全なプロンプト、レスポンス、検証	LLMデバッグ

進捗インジケーター (rich)

from rich.progress import Progress, SpinnerColumn, TextColumn

# For LLM calls (unknown duration)
with Progress(SpinnerColumn(), TextColumn("{task.description}")) as progress:
    task = progress.add_task("Generating output...", total=None)
    result = await llm.ainvoke(prompt)

# For multi-step pipelines (known steps)
from rich.progress import BarColumn, TaskProgressColumn
with Progress(BarColumn(), TaskProgressColumn()) as progress:
    task = progress.add_task("Pipeline", total=6)
    for stage in stages:
        await run_stage(stage)
        progress.advance(task)

テーブルとパネル

from rich.table import Table
from rich.panel import Panel

# Tabular data
table = Table(title="Pipeline Status")
table.add_column("Stage", style="cyan")
table.add_column("Status", style="green")
table.add_column("Tokens", justify="right")
table.add_row("Generate", "Complete", "1,234")
console.print(table)

# Summary panels
console.print(Panel(
    f"[green]Generation complete[/green]\n"
    f"Model: {result.model}\n"
    f"Tokens: {result.total_tokens}",
    title="Result",
))

エラーUX

# User-facing: rich panel with guidance
console.print(Panel(
    f"[red]Provider '{name}' not found.[/red]\n\n"
    f"Available: {', '.join(available)}\n"
    f"Set via: --provider, APP_PROVIDER env, or config file",
    title="Configuration Error",
    border_style="red",
))
raise typer.Exit(1)

# Never show raw tracebacks. Catch, format, guide.
# Show tracebacks only at -vvv verbosity.

インタラクティブモードとパイプラインモード

import sys
from rich.prompt import Confirm

def maybe_confirm(message: str) -> bool:
    """Prompt interactively, auto-yes in pipeline mode."""
    if not sys.stdin.isatty():
        return True  # Non-interactive: proceed
    return Confirm.ask(message)

すべてのインタラクティブなプロンプトに対して、フラグや環境変数などのノンインタラクティブな選択肢を常に提供します。

サブコマンドグループ

# Nested commands for complex CLIs
pipeline_app = typer.Typer(help="Pipeline operations")
app.add_typer(pipeline_app, name="pipeline")

@pipeline_app.command("run")
def pipeline_run(to: str = typer.Option("ship", help="Run up to stage")):
    """Execute pipeline stages."""

# Usage: mytool pipeline run --to seed