Installation

Prerequisites

  • Python 3.13+ (not tested on earlier versions)
  • uv — the fast Python package manager (install uv)
  • gh — the GitHub CLI, only needed if you use the --github flag (install gh)

Install

Install as a global tool with uv (recommended):

uv tool install uv-start

Or with pip:

pip install uv-start

Author configuration

Configure your author details so they are injected into every project you generate. Run this once after installing:

uv-start --config "Jane Doe" "jane@example.com"

This saves your name and email to ~/.config/uv-start/config.toml.

If you skip this step, uv-start falls back to your git config (user.name / user.email). If neither is set, placeholder values are used.

GitHub authentication

If you plan to use the --github flag, authenticate the gh CLI first using OAuth:

gh auth login

Follow the interactive prompts to authenticate via your browser. This stores credentials securely in the gh keychain — no tokens need to be stored in any file.

Note

If GH_TOKEN or GITHUB_TOKEN is already exported in your shell, gh will use it automatically. However, OAuth via gh auth login is the recommended approach.

Running uv-start

After installing, uv-start is available directly on your PATH. Run it from any directory that will become the parent of your new project (it must not itself be a git repository):

cd ~/projects
uv-start my-new-project -t package -g