click-app cookiecutter template
Cookiecutter template for creating new Click command-line tools.
Use this template on your own machine with cookiecutter, or create a brand new repository based on this template entirely through the GitHub web interface using click-app-template-repository.
You'll need to have cookiecutter installed. I recommend pipx for this:
pipx install cookiecutter
pip will work OK too.
Three examples of tools that were initially created using this template:
- shot-scraper: A comand-line utility for taking automated screenshots of websites
- s3-credentials: A tool for creating credentials for accessing S3 buckets
- git-history: Tools for analyzing Git history using SQLite
cookiecutter gh:simonw/click-app and then answer the prompts. Here's an example run:
$ cookiecutter gh:simonw/click-app app_name : click app template demo description : Demonstrating https://github.com/simonw/click-app hyphenated [click-app-template-demo]: underscored [click_app_template_demo]: github_username : simonw author_name : Simon Willison
I strongly recommend accepting the suggested value for "hyphenated" and "underscored" by hitting enter on those prompts.
This will create a directory called
click-app-template-demo - the tool name you enter is converted to lowercase and uses hyphens instead of spaces.
See https://github.com/simonw/click-app-template-demo for the output of this example.
Developing your command-line tool
Having created the new structure from the template, here's how to start working on the tool.
If your tool is called
my-new-tool, you can start working on it like so:
cd my-new-tool # Create and activate a virtual environment: python3 -m venv venv source venv/bin/activate # Install dependencies so you can edit the project: pip install -e '.[test]' # With zsh you have to run this again for some reason: source venv/bin/activate # Confirm your tool can be run from the command-line my-new-tool --version
You should see the following:
my-new-tool, version 0.1
You can run the default test for your tool like so:
This will execute the test in
Now you can open the
my_new_tool/cli.py file and start adding Click commands and groups.
Creating a Git repository for your tool
You can initialize a Git repository for your tool like this:
cd my-new-tool git init git add . git commit -m "Initial structure from template" # Rename the 'master' branch to 'main': git branch -m master main
Publishing your tool to GitHub
Use https://github.com/new to create a new GitHub repository sharing the same name as your tool, which should be something like
main branch to GitHub like this:
git remote add origin firstname.lastname@example.org:YOURNAME/my-new-tool.git git push -u origin main
The template will have created a GitHub Action which runs your tool's test suite against every commit.
Publishing your tool as a package to PyPI
The template also includes an Action for publishing packages to PyPI.
To use this action, you need to create a PyPI account and an API token against that account.
Once you have created your account, navigate to https://pypi.org/manage/account/token/ and create an API token. For initial publication of the package you will need to set the scope of the token to "Entire account (all projects)".
Add that token to your repository as a GitHub secret called
PYPI_TOKEN. You can find this in the "Settings -> Secrets -> New Secret" area of the repository. The token should begin with the string
Now, any time you create a new "Release" on GitHub the Action will build your package and push it to PyPI. The tag for the new release needs to match the
VERSION string at the top of your
After the first release has gone out you can create a new PyPI API token that is scoped just to that project and use that to replace the
PYPI_TOKEN secret in your GitHub repository settings.