{"id":37730018,"url":"https://github.com/jlevy/uvtemplate","last_synced_at":"2026-01-16T13:48:50.439Z","repository":{"id":285519594,"uuid":"958273888","full_name":"jlevy/uvtemplate","owner":"jlevy","description":"A time-saving CLI to start new, modern Python projects","archived":false,"fork":false,"pushed_at":"2026-01-15T03:27:15.000Z","size":127,"stargazers_count":51,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-15T04:55:44.789Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jlevy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-31T23:42:44.000Z","updated_at":"2026-01-15T03:27:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"1e6096ef-06c6-4e5c-b116-49834f912dd9","html_url":"https://github.com/jlevy/uvtemplate","commit_stats":null,"previous_names":["jlevy/uvinit"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/jlevy/uvtemplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fuvtemplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fuvtemplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fuvtemplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fuvtemplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlevy","download_url":"https://codeload.github.com/jlevy/uvtemplate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fuvtemplate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-16T13:48:49.839Z","updated_at":"2026-01-16T13:48:50.421Z","avatar_url":"https://github.com/jlevy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003c!-- \u003cimg alt=\"Using uvtemplate\" src=\"https://github.com/user-attachments/assets/4325c251-26b7-4c4c-b46f-00759e53f7ae\" /\u003e --\u003e\n\u003cimg alt=\"Using uvtemplate\" src=\"https://github.com/user-attachments/assets/8d048d1c-4fef-4c0c-aa9b-e05885ff4fbf\" /\u003e\n\n\u003c/div\u003e\n\n# uvtemplate\n\n[![Documentation](https://img.shields.io/badge/documentation-go)](https://www.github.com/jlevy/simple-modern-uv)\n[![CI status](https://github.com/jlevy/uvtemplate/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/uvtemplate/actions/workflows/ci.yml?query=branch%3Amain)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/uvtemplate.svg?v=1)](https://pypi.python.org/pypi/uvtemplate)\n[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)\n[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-border.json)](https://github.com/copier-org/copier)\n[![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/ojoshe)](https://x.com/ojoshe)\n\nA time-saving CLI tool to quickly start new Python projects with\n[**uv**](https://github.com/astral-sh/uv) using the\n[**simple-modern-uv**](https://github.com/jlevy/simple-modern-uv) template.\n\n## Quick Start\n\n### For Humans (Interactive Mode)\n\n```bash\nuvx uvtemplate create\n```\n\nThis will guide you through creating a new project step by step.\n\n### For AI Agents (Non-Interactive Mode)\n\nAI coding agents like Claude Code can create projects programmatically:\n\n```bash\nuvx uvtemplate --yes --destination my-project \\\n  --data package_name=my-project \\\n  --data package_description=\"My awesome project\" \\\n  --data package_author_name=\"Your Name\" \\\n  --skip-git\n```\n\n## Do I Need uv?\n\nYes. You will need to [**have uv installed**](https://github.com/astral-sh/uv).\nRead that page or my [template docs](https://github.com/jlevy/simple-modern-uv) for\nbackground on why uv is such an improved package manager for Python.\n\n## What is uvtemplate?\n\nIt’s the tool I wish I’d had when setting up projects with uv.\n\n**`uvx uvtemplate create`** will clone a new project template and help you set up your\nGitHub repo. The template is tiny and sets up **uv**, **ruff** linting and formatting,\n**GitHub Actions**, **publishing to PyPI**, **type checking**, and more.\n\n## Usage\n\n### Commands\n\n| Command | Description |\n| --- | --- |\n| `uvtemplate` | Show help and available options |\n| `uvtemplate create` | Start interactive project creation |\n| `uvtemplate migrate` | Analyze an existing project and show migration recommendations |\n| `uvtemplate update` | Update a template-based project to the latest template version |\n| `uvtemplate readme` | Print this documentation |\n\n### Options\n\n| Option | Description |\n| --- | --- |\n| `--destination DIR` | Destination directory for the project |\n| `--data KEY=VALUE` | Set a template value (can be repeated) |\n| `--yes` | Auto-confirm all prompts (non-interactive mode) |\n| `--skip-git` | Skip GitHub repository and git setup |\n| `--template URL` | Use a custom copier template |\n| `--answers-file FILE` | Load defaults from a .copier-answers.yml file |\n| `--no-gh-cli` | Don't use gh CLI to create repo |\n| `--public` | Create a public repository (default: private) |\n| `--git-protocol ssh | https` |\n\n### Template Values\n\nUse `--data KEY=VALUE` to set these values:\n\n| Key | Description | Example |\n| --- | --- | --- |\n| `package_name` | Package name (kebab-case) | `my-project` |\n| `package_module` | Python module name (snake_case) | `my_project` |\n| `package_description` | Short description | `\"A useful tool\"` |\n| `package_author_name` | Author's name | `\"Jane Doe\"` |\n| `package_author_email` | Author's email | `\"jane@example.com\"` |\n| `package_github_org` | GitHub username or org | `\"janedev\"` |\n\n## Examples\n\n### Interactive (Human) Usage\n\nStart the interactive wizard:\n\n```bash\nuvx uvtemplate create\n```\n\nSkip git setup (just create the project files):\n\n```bash\nuvx uvtemplate create --skip-git\n```\n\n### Non-Interactive (Agent) Usage\n\nCreate a complete project without any prompts:\n\n```bash\nuvx uvtemplate --yes --destination my-cli-tool \\\n  --data package_name=my-cli-tool \\\n  --data package_module=my_cli_tool \\\n  --data package_description=\"A command-line tool for doing things\" \\\n  --data package_author_name=\"Claude\" \\\n  --data package_author_email=\"ai@example.com\" \\\n  --data package_github_org=\"myorg\" \\\n  --skip-git\n```\n\nCreate a project and set up a private GitHub repo:\n\n```bash\nuvx uvtemplate --yes --destination my-project \\\n  --data package_name=my-project \\\n  --data package_description=\"My project\" \\\n  --data package_github_org=\"myorg\"\n```\n\nCreate a project with a public GitHub repo:\n\n```bash\nuvx uvtemplate --yes --destination my-project \\\n  --data package_name=my-project \\\n  --public\n```\n\n### Using an Answers File\n\nIf you have a `.copier-answers.yml` from a previous project:\n\n```bash\nuvx uvtemplate --yes --destination new-project \\\n  --answers-file /path/to/existing/.copier-answers.yml\n```\n\n## For AI Coding Agents\n\nThis tool is designed to work well with AI coding agents like Claude Code, Cursor,\nGitHub Copilot, etc.\n\n### Key Points for Agents\n\n1. **Use `--yes` flag**: This auto-confirms all prompts, making the tool fully\n   non-interactive.\n\n2. **Provide all values via `--data`**: Set template values upfront to avoid interactive\n   prompts.\n\n3. **Use `--skip-git`** if you want to handle git setup separately or don’t need it.\n\n4. **The tool uses exit codes**: `0` for success, `1` for failure/cancellation.\n\n5. **Values are derived intelligently**: If you provide `--destination my-project`, the\n   tool will automatically derive `package_name=my-project` and\n   `package_module=my_project` unless you override them.\n\n### Minimal Agent Example\n\nThe simplest non-interactive usage:\n\n```bash\nuvx uvtemplate --yes --destination my-project --skip-git\n```\n\nThis creates a project with sensible defaults derived from the destination name and your\ngit/GitHub config.\n\n### Complete Agent Example\n\nFor full control:\n\n```bash\nuvx uvtemplate --yes --destination my-project \\\n  --data package_name=my-project \\\n  --data package_module=my_project \\\n  --data package_description=\"Project description here\" \\\n  --data package_author_name=\"Author Name\" \\\n  --data package_author_email=\"author@example.com\" \\\n  --data package_github_org=\"github-org\" \\\n  --skip-git\n```\n\n## What Python Project Template Does it Use?\n\nThe [**simple-modern-uv**](https://github.com/jlevy/simple-modern-uv) template.\nSee that repo for full docs and\n[this thread](https://x.com/ojoshe/status/1901380005084700793) for a bit more context.\n\nThe template includes:\n\n- **uv** for project setup and dependencies\n\n- **ruff** for modern linting and formatting\n\n- **GitHub Actions** for CI and publishing workflows\n\n- **Dynamic versioning** from git tags\n\n- **PyPI publishing** workflows\n\n- **BasedPyright** for type checking\n\n- **Pytest** for tests\n\n- **Codespell** for spell checking\n\nIf you prefer, you can use that template directly; uvtemplate is just a CLI wrapper.\n\nIf you have another copier-format template you want to use, specify it with\n`--template`.\n\n## Migrating an Existing Project\n\nUse the `migrate` command to analyze an existing project and get migration\nrecommendations:\n\n```bash\ncd my-existing-project\nuvx uvtemplate migrate\n```\n\nThis will detect your current build system (Poetry, setuptools, Pipenv, etc.)\nand provide a step-by-step guide for migrating to uv.\nIt analyzes your project and outputs recommendations—it does not automatically modify\nany files.\n\nThe migrate command works well with AI agents, providing structured recommendations that\nan agent can follow to perform the migration.\n\n### Alternative: Manual Migration\n\nYou can also create a fresh template as a reference and manually copy what you need:\n\n```bash\nuvtemplate create --skip-git --destination .uvtemplate-ref\n```\n\nThen copy the relevant files (pyproject.toml structure, Makefile, workflows, etc.)\ninto your existing project.\n\n## Updating a Project\n\nProjects created with uvtemplate can be updated to the latest template version:\n\n```bash\ncd my-project\nuvx uvtemplate update\n```\n\nThis uses [copier](https://github.com/copier-org/copier) under the hood to apply\ntemplate updates while preserving your customizations.\nThe command will show you what changed and let you resolve any conflicts.\n\nFor non-interactive updates (useful for AI agents):\n\n```bash\nuvx uvtemplate update --yes\n```\n\nNote: The `update` command only works on projects that were created with uvtemplate (or\ncopier directly). If you migrated a project manually, use `uvtemplate migrate` to see\nrecommendations.\n\n* * *\n\n*This project was (of course) built using\n[simple-modern-uv](https://github.com/jlevy/simple-modern-uv).*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlevy%2Fuvtemplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlevy%2Fuvtemplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlevy%2Fuvtemplate/lists"}