create-forge

Scaffold modern Python projects from maintained templates — and pull template improvements back into projects you generated months ago.

uvx create-forge new

No install step. Requires uv and git.

Why

Most project generators are fire-and-forget: you scaffold once, and from that moment your project drifts away from the template. Six months later the template has better lint rules, a security fix in CI, and a newer toolchain — and no path to get any of it into projects already in the wild.

create-forge is built on Copier, which does a three-way merge between the template version your project was generated from and the latest one. Local edits survive; template changes arrive.

uvx create-forge update

What you get

Every generated project ships with:

• uv for packaging and dependency management
• Ruff for linting and formatting
• mypy or pyright (or both) for type checking
• pytest with coverage
• pre-commit hooks, including Conventional Commits enforcement
• GitHub Actions CI, with a test matrix across your supported Python versions
• Renovate or Dependabot for dependency updates
• README, CONTRIBUTING, SECURITY, CHANGELOG, issue and PR templates
• Optionally: a MkDocs documentation site and ADR scaffolding

Choices you make at scaffold time — build backend, versioning strategy, license, type checker — are remembered, so updates respect them.

Usage

# Interactive
uvx create-forge new

# Named up front
uvx create-forge new "Credit Risk Utils"

# Non-interactive, for scripts and CI
uvx create-forge new "My Lib" --yes \
  --data build_backend=hatchling \
  --data versioning=vcs \
  --data type_checking=both

Useful flags on new: --template/-t, --path/-p, --data/-d, --yes/-y, --ref, --dry-run.

Configuration

Optional. Saves retyping the same answers:

# ~/.config/create-forge/config.toml
author_name = "Your Name"
author_email = "you@example.com"
github_org = "your-org"
default_template = "library"

create-forge config init writes a commented starter file at that path without overwriting one that already exists. create-forge config show prints the resolved values and where each came from.

github_org pre-fills its prompt — you're still asked, just with the answer already typed in. author_name and author_email aren't prompted for at all, so a configured value is applied directly. default_template picks which template new offers first, interactively or under --yes.

Every key can be overridden with an environment variable — FORGE_GITHUB_ORG and so on — or a command line flag. Precedence is config < environment < --data < an interactive answer.

Templates

Run create-forge list for what your installed version offers. The registry is bundled with each release, so new templates arrive when you update the tool.

To use your own template:

uvx create-forge new --template-url https://github.com/you/your-template

This describes the released v0.1.x architecture. Forge has accepted a future public-engine integration contract in which a versioned forge-template package owns discovery and rendering. Its strict ProjectSpec protocol v1 and component manifest protocol v1 are now implemented behind the canonical stable template-engine API (ADR 0029). The accepted Library archetype contract defines the first production component, implemented on forge-template/main and released at 0.3.0. The accepted CLI Application archetype contract selects the optionless engine-owned cli archetype and derives its console command from ProjectSpec.project.repository_name; FT-08.04 implemented it in the same 0.3.0 release, and CF-08.02 exposes both archetypes behind the hidden new --engine-preview flag's --archetype option. Neither change alters this CLI's default new answers, registry, or released dependency surface. The Stage 08 composition architecture review is released in forge-template 0.3.2. On the engine-preview path, create-forge 0.2.1 now finalises the validated in-memory render with uv lock --directory <staging-directory> before the atomic rename. The result contains uv.lock and uses uv run --locked poe check, while the default Copier path remains unchanged; see ADR 0021. The engine now also defines in-memory generated-project validation (ADR 0030) before rendered output is returned; render_project already calls it before --engine-preview receives a result. This repository now depends on a real, released forge-template range — >=0.3.1,<0.4, published to PyPI with uv>=0.12,<0.13 as the optional engine extra (pip install 'create-forge[engine]'; #9, ADR 0018) — rather than a development-only pin. That range is reachable only behind --engine-preview; the current registry and --template-url behaviour remain unchanged until the complete, tested cutover is released — at which point --engine-source/--engine-ref (see the engine resolution contract) take over this role, not --template-url.

Security

create-forge executes code from the template it clones. Copier templates can declare post-generation tasks, and this tool runs them — that is how a generated project arrives already git-initialised with hooks installed.

The template addresses are compiled into each release rather than fetched at runtime or read from user configuration, so the only code trusted by default is code published alongside the tool. --template-url bypasses that, and prompts for confirmation before doing so. Point it only at repositories you trust.

Report vulnerabilities per SECURITY.md rather than in a public issue.

Using this at work

In v0.1.x, organisations needing custom executable templates can fork this repository, point the bundled registry at their own templates, and maintain it internally. The accepted target makes a downstream client of the forge-template public engine the preferred route for organisation defaults and constraints. Forks remain appropriate for genuinely custom executable template content; see the integration contract.

Contributing

See CONTRIBUTING.md. Issues and pull requests welcome. Significant design decisions are recorded in docs/adr/.

License

MIT — see LICENSE.