Command Reference

This is the reference guide for generate-project, a command-line tool for generating Python project folders with pre-configured development tasks for formatting, linting, documentation, testing, release management and CI/CD.

Commands Overview

generate-project provides two commands:

generate: Create a new Python project folder with configurable parameters
config: Configure default project parameters

For quick help use:

generate-project --help
generate-project --version
generate-project generate --help
generate-project config --help

Global Options

Option	Description
`--help`	Show help message and exit
`--version`	Show program version and exit

generate Command

Create a new Python project folder with comprehensive development setup.

Synopsis

generate-project generate PROJECT_NAME [OPTIONS]

Arguments

Required Arguments

Argument	Description
`PROJECT-NAME`	Name of the project to create

generate-project will create a new subdirectory named PROJECT-NAME in your current working directory and populate it with the project template. If you want to generate the project in an existing directory without creating a subdirectory, use . as the project name.

Project Configuration Options

These options configure the project metadata and can be saved as defaults using the config command:

Option	Description
`--author_name`	Author’s full name
`--email`	Author’s email address
`--github_username`	GitHub username for repository creation
`--version`	Initial project version number
`--description`	Short project description
`--python_min_version`	Minimum Python version
`--package_name`	Python package name (can be auto-generated from project name)
`--autodoc_mock_imports`	Comma-separated list of modules to mock for Sphinx autodoc
`--complex_mock_modules`	Comma-separated list of complex modules requiring special mocking
`--google_analytics_id`	Google Analytics tracking ID for documentation SEO metrics

Behavior Control Options

Option	Description	Default
`--no-install`	Skip installing dependencies	Install dependencies
`--no-git`	Skip Git repository initialization	Initialize Git repository

Project Type Options

Option	Description	Default
`--library`	Create a library project (no CLI entry point)	Application project
`--manager`	Package manager: `poetry` or `uv`	`poetry`

When --manager uv is specified:

Uses hatchling build backend instead of poetry-core
Uses PEP 621 [project] metadata and [dependency-groups] (PEP 735)
CI workflows use astral-sh/setup-uv instead of Poetry
run.sh uses uv sync, uv run, uv build, uv publish

When --library is specified:

No [project.scripts] section is added to pyproject.toml
No main.py CLI entry point is created
README focuses on API usage instead of CLI usage

GitHub Integration Options (requires gh CLI)

Option	Description	Default
`--github`	Create a private GitHub repository	No repository creation
`--public`	Create a public GitHub repository	Private repository
`--secrets`	Create GitHub repository secrets for PyPl and RTD integration	No secrets creation

GitHub repository secrets are used by GitHub CI/CD actions and automated publishing tasks:

    make release-major        # Create major release
    make release-minor        # Create minor release
    make release-micro        # Create micro (patch) release
    make release-rc           # Create release candidate
    make release-beta         # Create beta pre-release
    make release-alpha        # Create alpha pre-release

Manual Publishing Setup Options

Option	Description	Default
`--local-env`	Create local `.env` file with tokens in project directory	No .env creation

This local .env file will be used for manual publishing tasks:

    make publish-test         # Publish to TestPyPI
    make publish              # Publish to PyPI

File Path Options

Option	Description	Default
`--env`	Path to .env file containing tokens for repository secrets	`.env` with location auto-detect
`--template`	Path to custom cookiecutter template	Built-in template (selected by `--manager`)

Examples

Basic Project Creation

generate-project generate my-project

Custom Project with Metadata

generate-project generate my-project \
    --author_name="John Doe" \
    --email="john@example.com" \
    --description="An awesome Python library"

Full Setup with GitHub and Publishing

generate-project generate my-project \
    --author_name="John Doe" \
    --email="john@example.com" \
    --github_username="johndoe" \
    --public \
    --secrets \

Create UV Project

generate-project generate my-project --manager uv

Using Custom Template

generate-project generate my-project \
    --template="/path/to/custom/template" \
    --author_name="John Doe"

Generate Project in Current Directory

# Navigate to your project directory first
cd my-project

# Generate project files in current directory
generate-project generate .

This approach is useful when you want to use a customized .env file for the project. In this case, manually create the project directory and then, inside the directory, create the .env file and run generate-project generate ..

Publishing Setup

The --secrets and --local-env options enable automated and manual publishing workflows. They require an .env file with the following tokens:

# .env file
TEST_PYPI_TOKEN=pypi-...      # Token for TestPyPI publishing
PYPI_TOKEN=pypi-...           # Token for PyPI publishing  
RTD_TOKEN=rtd_...             # Token for ReadTheDocs publishing

Token Location

The .env file should be located in one of the following locations (searched in order):

Path specified by --env option
Current working directory
Parent directories (searched upward)
If no .env file is found, the application falls back to reading the tokens from environment variables.

Publishing Options Explained

GitHub Secrets (--secrets):
Creates GitHub epository secrets from .env tokens, enabling automated publishing to PyPI and RTD through CI/CD workflows. Requires GitHub CLI authentication.

Local .env (--local-env):
Creates a project-specific .env file in the project directory to be used by manual publishing tasks. This is useful to freeze the publishing credentials of the project.

config Command

Configure default values for project configuration parameters. These defaults will be used automatically in future generate commands.

Synopsis

generate-project config [OPTIONS]

Options

The config command accepts the same project configuration options as the generate command:

Option	Description
`--author_name`	Set default author name
`--email`	Set default email address
`--github_username`	Set default GitHub username
`--version`	Set default initial version
`--description`	Set default project description
`--python_min_version`	Set default minimum Python version
`--manager`	Set default package manager (`poetry` or `uv`)
`--autodoc_mock_imports`	Set default autodoc mock imports
`--complex_mock_modules`	Set default complex mock modules
`--google_analytics_id`	Set default Google Analytics ID

Configuration File

The configuration is stored in /templates/config.yaml within the folder where the application is installed and follows this format:

default_context:
  author_name: Your Name
  email: your.email@example.com
  github_username: yourusername
  version: 0.0.0
  # ... other defaults

Examples

Set Personal Defaults

generate-project config \
    --author_name="John Doe" \
    --email="john@example.com" \
    --github_username="johndoe" \

Update Project Defaults

generate-project config \
    --description="My project" \
    --python_min_version="3.10" \
    --version="0.0.0"

After setting defaults, you can omit these parameters in future generate commands.

Generated Project Structure

The generate command creates a complete Python project with the following structure:

project-name/
├── .github/workflows/         # GitHub actions for CI/CD
│   ├── docs.yml               # Documentation building and testing
│   ├── tests.yml              # Code quality and testing
│   ├── release.yml            # Automated releases and publishing
│   └── update_rtd.yml         # Manual ReadTheDocs updates
├── .vscode/                   # VS Code configuration
│   ├── settings.json          # Editor settings, linting, formatting
│   ├── launch.json            # Debug configurations
│   └── tasks.json             # Task definitions
├── docs/                      # Sphinx documentation
│   ├── api/                   # Auto-generated API docs
│   ├── guides/                # User guides
│   ├── conf.py                # Sphinx configuration
│   └── index.md               # Documentation home
├── src/package_name/          # Source code
│   └── __init__.py            # Package initialization
├── tests/                     # Test directory
├── scripts/                   # Release management scripts
├── .env                       # Environment variables (if --local-env used)
├── .gitignore                 # Git ignore rules
├── .readthedocs.yaml          # ReadTheDocs configuration
├── CLAUDE.md                  # Claude Code integration guide
├── CredentialManagement.md    # Token management documentation
├── LICENSE                    # MIT License
├── Makefile                   # Development commands
├── pyproject.toml             # Project configuration
├── run.sh                     # Development task runner
└── README.md                  # Project documentation

Integration with Development Workflow

The generated projects include comprehensive development tooling:

Code Quality Tools

Black: Code formatting
isort: Import sorting
flake8: Linting and style checking
mypy: Static type checking
pylint: Advanced linting and code analysis

Testing Framework

pytest: Test runner with plugin support
pytest-cov: Coverage reporting

Documentation System

Sphinx: Documentation generation
MyST-Parser: Markdown support in Sphinx
autodoc: Automatic API documentation from docstrings
ReadTheDocs: Automated documentation hosting

CI/CD Workflows

Tests: Run on pull requests and pushes
Docs: Build and validate documentation
Release: Automated PyPI publishing on new version (using git tags)
RTD Update: Manual documentation updates

Development Workflow

The generated project includes a Makefile with common development tasks:

# Environment Setup
make venv                 # Create and activate a local virtual environment
make install              # Install core dependencies
make install-dev          # Install all development dependencies

# Code quality
make format               # Run code formatters
make lint                 # Run linters
make check                # Run format + lint + tests on all files
make pre-commit           # Run format and lint only on changed files, then tests

# Testing
make test                 # Run tests
make test-cov             # Run tests with coverage
make coverage             # Generate coverage report

# Documentation
make docs-api             # Generate API documentation
make docs                 # Build documentation
make docs-live            # Start live preview server


# Release tasks will bump the version, create a new release and publish it
make release-major        # Create major release
make release-minor        # Create minor release
make release-micro        # Create micro (patch) release
make release-rc           # Create release candidate
make release-beta         # Create beta pre-release
make release-alpha        # Create alpha pre-release

Run make help for a complete list of the development tasks available.

Error Handling

Common Issues

Missing Authentication Secrets

Error: Cannot create GitHub secrets or .env file.
The following environment variables are missing:

Solution: Make sure that the authentication tokens (TEST_PYPI_TOKEN, PYPI_TOKEN and RTD_TOKEN) are available on a .env file or as environment variables.

GitHub CLI Not Installed

Error: GitHub CLI (gh) not installed.
Install it from: https://cli.github.com/

Solution: Install the GitHub CLI from https://cli.github.com/

GitHub CLI Not Authenticated

Error: GitHub CLI not authenticated.
Run: gh auth login

Solution: Authenticate with GitHub CLI using gh auth login and follow the prompts.

Project Directory Already Exists

Error: Directory <project-name> already exists.

Solution: Either use a different project name, remove the existing directory, or use . to generate the project inside an existing directory.

Project File Already Exists

Error: Cannot generate into existing directory, conflicting files: <file1>, <file2>, ...

Solution: When using . as the project name, make sure that the current directory does not contain any files or subdirectories that collide with the project template structure.