Skip to content

Getting Started with pyclif

Installation

Install pyclif using pip:

pip install pyclif

Requirements

  • Python 3.10 or higher
  • Dependencies are automatically installed

Quickstart with scaffolding

The fastest way to get a production-ready project is to let pyclif generate it for you:

# Create a new project
pyclif project init my-project
cd my-project

# Install dependencies
uv sync --dev

# Run the generated CLI
uv run my-project --help

From there, add feature areas and commands incrementally:

# Add a feature area (app)
pyclif project add app users

# Add commands to it
pyclif project add command list   --app users
pyclif project add command create --app users

# Wrap an external service
pyclif project add integration github --package

Everything gets wired automatically — no manual imports to update. See the Scaffolding guide for the full reference.

Manual setup

If you prefer to understand each piece or are adding pyclif to an existing project, here's a minimal example to get you started:

from pyclif import app_group, command, option


@app_group()
def main():
    """My CLI application."""
    pass


@main.command()
@option("--name", "-n", help="Your name")
def hello(name):
    """Say hello."""
    print(f"Hello {name}!")


if __name__ == "__main__":
    main()

Save this as my_cli.py and run it:

python my_cli.py --help
python my_cli.py hello --name "World"
python my_cli.py hello -n "Alice"

Building your first CLI manually

Step 1: Create the main group

from pyclif import app_group


@app_group(
    name="myapp",
    auto_envvar_prefix="MYAPP"
)
def cli():
    """My Application — a sample CLI built with pyclif."""
    pass

Step 2: Add a simple command

from pyclif import app_group, option


@app_group(name="myapp", auto_envvar_prefix="MYAPP")
def cli():
    """My Application."""
    pass


@cli.command()
@option("--message", "-m", default="Hello World", help="Message to display")
def hello(message):
    """Display a greeting message."""
    print(message)

Step 3: Add a command group

from pyclif import group, option


@group(name="database")
def database():
    """Database management commands."""
    pass


@database.command()
@option("--url", "-u", required=True, help="Database URL")
@option("--timeout", "-t", type=int, default=30, help="Connection timeout")
def connect(url, timeout):
    """Connect to the database."""
    print(f"Connecting to {url} with timeout {timeout}s")

Step 4: Run your CLI

if __name__ == "__main__":
    cli()

Automatic Features

When you use @app_group, you automatically get:

  • Help options: -h and --help
  • Version option: --version
  • Verbosity options: -v, -vv, -vvv (propagated globally to all subcommands)
  • Configuration option: --config / -C
  • Output format option: --output-format / -o
  • Environment variable support: With your custom prefix

Execution timer

Pass timer=True to enable a --time/--no-time flag:

@app_group(handle_response=True, timer=True)
def cli():
    """My CLI."""

my-app --time deploy
# rich/table/raw → prints: Execution time: 1.234 seconds.
# json/yaml      → injects {"execution_time": 1.234, "execution_time_str": "1.234s"} into Response.data

Testing Your CLI

# Show help
python my_cli.py --help

# Use environment variables
export MYAPP_MESSAGE="Hello from environment!"
python my_cli.py hello

# Use a configuration file
python my_cli.py --config /path/to/config.toml hello

# Use verbosity
python my_cli.py -vv hello --message "Debug mode"

Next Steps