Quick guide to convert a Python script into a CLI tool

Reading the Click’s documentation will bring you up to speed on what it can do, but I’m writing a quick list of steps I follow every time I need to make a quick CLI out of a Python script.

So, let’s start by creating a Python project and installing Click as a dependency.

$ poetry new cool-tool
$ cd cool-tool
$ poetry add click

Poetry will create a scaffold directory that looks like this:

cool-tool/
  cool_tool/
    __init__.py
  poetry.lock
  pyproject.toml

For this example, we will create a main.py file with a very cool function.

$ cd cool-tool 
$ touch cool_tool/main.py

In our file we create a function and some logic.

# main.py
def cool():
  print("hello cool world")

OK, now to the part we really care. Let’s convert this script into a CLI

• create a directory named “console” inside our main module.
• create a __init__.py file to let Python know this is a module.
• create a run.py file where we will add our Click logic.

$ mkdir console
$ touch console/__init__.py
$ touch console/run.py

Inside our run.py we add:

import os
import click
from cool_tool.main import cool

@click.group
def cli():
   pass


@click.command
@click.argument("cool")
def show_cool():
   click.echo(cool())

Then we add our CLI script to our pyproject.toml so we can use it directly inside our virtual environment, e.g., cool --help. Add this section and we should be done:

# pyproject.toml
[tool.poetry.scripts]
cool = 'cool_tool.console.run:cli'

Run poetry install, make sure you have the virtual environment activated, and verify everything works by running the help command.

$ poetry install
$ poetry shell
$ cool --help

Usage: cool [OPTIONS] COMMAND [ARGS]...

Options:
  --help Show this message and exit.

Commands:
  show_cool

Resources

• Poetry’s scripts documentation