Click

decorator 조합으로 command, option, argument, group을 구성하는 Python CLI framework다.

• @click.command(), @click.option(), @click.argument()로 함수를 CLI로 변환한다.
• @click.group()으로 중첩 가능한 subcommand tree를 만든다.
• help, type conversion, prompt, environment variable, terminal 출력, testing 도구를 제공한다.

공식 문서는 virtual environment에서 PyPI package를 설치하도록 안내한다.

# Linux / macOS
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install click
python3 -c "import importlib.metadata; print(importlib.metadata.version('click'))"

# Windows PowerShell
py -m venv .venv
.venv\Scripts\Activate.ps1
py -m pip install click
py -c "import importlib.metadata; print(importlib.metadata.version('click'))"

Click가 공식적으로 별도 안내하는 APT, DNF/YUM, Homebrew, winget package는 없다. Python project dependency로 설치한다.

import click
 
@click.command()
@click.argument("name")
@click.option("--count", default=1, type=int, show_default=True)
@click.option("--verbose", is_flag=True, help="상세 출력")
def hello(name: str, count: int, verbose: bool):
    """NAME에게 인사합니다."""
    if verbose:
        click.echo(f"count={count}", err=True)
    for _ in range(count):
        click.echo(f"Hello, {name}!")
 
if __name__ == "__main__":
    hello()

python3 hello.py --help
python3 hello.py World --count 2 --verbose

• python3 HELLO.py NAME [–count COUNT] [–verbose]
• –count COUNT: integer option
• –verbose: 값 없는 boolean flag
• –help: 자동 생성된 help 표시

import click
 
@click.group()
def cli():
    """프로젝트 관리 CLI."""
 
@cli.command()
@click.argument("name")
def init(name: str):
    """새 프로젝트를 생성합니다."""
    click.echo(f"Initialized {name}")
 
@cli.command(deprecated=True)
def cleanup():
    """이전 cache를 정리합니다."""
    click.echo("Cleaned")
 
if __name__ == "__main__":
    cli()

• python3 PROJECT.py init NAME
• python3 PROJECT.py cleanup: deprecated warning을 출력하는 예제 command

• @click.command() : callback 함수를 Command로 변환
• @click.group() : child command를 가질 수 있는 Group 생성
• @click.option() / @click.argument() : option과 positional argument 선언
• @click.pass_context / @click.pass_obj : context 또는 공유 object 전달
• click.echo() / click.secho() : Unicode와 color 처리를 고려한 출력
• click.prompt() / click.confirm() : 대화형 입력
• click.Path / click.File / click.Choice : 자주 쓰는 parameter type
• click.ClickException / click.UsageError : 사용자에게 보여 줄 CLI 오류

@click.command()
@click.option("--username", envvar="APP_USERNAME", required=True)
def greet(username):
    click.echo(f"Hello {username}")

APP_USERNAME=alice python3 app.py

group 전체에는 auto_envvar_prefix를 적용할 수 있다. 명시적 command-line 값과 환경 변수의 우선순위를 함께 문서화한다.

설치 가능한 CLI는 pyproject.toml의 entry point로 연결한다.

[project]
name = "hello-cli"
version = "0.1.0"
dependencies = ["click>=8.1"]
 
[project.scripts]
hello = "hello_cli.main:hello"

python3 -m pip install -e .
hello --help

• group option은 subcommand option과 별개다. tool –debug run과 tool run –debug는 같은 위치로 처리되지 않는다.
• callback parameter 이름과 option의 destination 이름이 일치하는지 확인한다.
• test에서는 subprocess 대신 click.testing.CliRunner로 exit code, output, exception을 검사할 수 있다.
• library 내부에서 임의로 sys.exit()을 호출하기보다 Click exception 또는 callback return 구조를 사용하면 테스트가 쉽다.

• 이 환경에는 Click library가 설치되어 있지만 독립 click executable은 제공되지 않는다. 작성한 Python application 또는 package entry point를 실행한다.
• application에서 요구하는 Python 및 Click 최소 version을 dependency metadata에 고정한다.

Click 자체의 공통 click –help 명령은 없다. 작성한 command마다 자동 생성되는 help를 확인한다.

python3 hello.py --help
python3 project.py --help
python3 project.py init --help

• Python
• Typer
• argparse
• Click 공식 문서
• Click 공식 문서: Quickstart
• Click 공식 문서: Commands and Groups
• Click 공식 문서: Packaging Entry Points

• codex:: 2026-08-03 Click 설치, decorator, command group, environment variable과 packaging 사용법을 정리.