python-cli

Click を使った Python CLI

合成可能なサブコマンドグループを使って、Click で Python CLI を構成します。

プロジェクト構成

.
├── pyproject.toml              # console_script points to `your_package.cli:main`
└── your_package/
    ├── __init__.py
    ├── cli.py                  # root Click group; imports and registers subcommands
    ├── foo/
    │   ├── __init__.py
    │   └── commands.py         # exposes a Click group named `cli`
    └── bar/
        ├── __init__.py
        └── commands.py         # exposes a Click group named `cli`

ルート CLI のエントリーポイント

import click

from .foo.commands import cli as foo
from .bar.commands import cli as bar

CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}


@click.group(context_settings=CONTEXT_SETTINGS)
def cli() -> None:
    """Project command line interface."""
    pass


@cli.command()
@click.option("--name", "-n", default="world", help="Who to greet.")
def hello(name: str) -> None:
    """Example subcommand."""
    click.echo(f"Hello, {name}!")


def main() -> None:
    cli()

# Register imported subcommand groups with explicit names
cli.add_command(foo, name="foo")
cli.add_command(bar, name="bar")


if __name__ == "__main__":
    main()

サブコマンドモジュール（foo/commands.py）

import click


@click.group()
def cli() -> None:
    """Foo subcommands."""
    pass


@cli.command()
@click.argument("item")
def process(item: str) -> None:
    """Process a single item."""
    click.echo(f"Processing: {item}")

pyproject.toml のエントリーポイント

[project.scripts]
my-tool = "your_package.cli:main"

主なパターン

• モジュールごとに 1 つのグループ：各サブコマンドディレクトリで、cli という名前の Click グループをエクスポートします
• 明示的な登録：ルート CLI で cli.add_command(group, name="name") を使用します
• コンテキスト設定：常に help_option_names = ["-h", "--help"] を設定します
• コンソールスクリプト：uv pip install -e . でインストールできるよう、pyproject.toml でエントリーポイントを設定します

記録の管理

CLI を変更した後は、現在のコマンド構成を反映するように、隣接する README.md を更新してください。