Skip to main content

​
Overview

The init command transforms a basic Python project into a fully-configured, production-ready pyrig project through a comprehensive automated sequence. It orchestrates the entire project setup process, from version control initialization to running tests and creating the first commit. 
uv run pyrig init

​
What It Does

The initialization sequence executes the following steps in order:
1

Initialize version control

Runs git init to create a new Git repository if one doesn’t exist.
2

Add development dependencies

Executes uv add --group dev to install all required development tools.
3

Sync virtual environment

Runs uv sync to ensure all dependencies are installed and up-to-date.
4

Create project root

Calls mkroot to generate all configuration files and directory structure.
5

Re-sync environment

Runs uv sync again to apply the newly generated configurations.
6

Generate test skeletons

Calls mktests to create test files mirroring the source structure.
7

Install pre-commit hooks

Executes prek install to set up Git hooks for code quality enforcement.
8

Stage all files

Runs git add . to add all generated files to version control.
9

Run pre-commit hooks

Executes pre-commit hooks to format and lint all files.
10

Run test suite

Executes pytest to ensure all generated tests pass.
11

Create initial commit

Makes the first Git commit with all project files.

​
Usage

​
First-Time Project Setup

# Start with a new directory
cd my-project
uv init
uv add pyrig
uv run pyrig init

​
Expected Output

$ uv run pyrig init
Initializing git repository...
Adding development dependencies...
Syncing virtual environment...
Creating project configuration files...
Generating test skeletons...
Installing pre-commit hooks...
Running pre-commit hooks...
Running test suite...
Creating initial commit...
✓ Project initialized successfully!

​
With Verbose Output

# See detailed step-by-step output
uv run pyrig -v init

# See module-level debugging
uv run pyrig -vv init

# See full diagnostic output with timestamps
uv run pyrig -vvv init

​
Quiet Mode

# Only show warnings and errors
uv run pyrig -q init

​
What You Get

After running init, your project will have:
  • Configuration files: pyproject.toml, .gitignore, .pre-commit-config.yaml, etc.
  • GitHub workflows: CI/CD pipelines in .github/workflows/
  • Test structure: Complete test skeleton mirroring your source code
  • Git hooks: Pre-commit hooks for formatting and linting
  • Working CLI: Automatically generated CLI for your project
  • Initial commit: All files committed to version control

​
Behavior

​
Execution
sequential
Each step executes sequentially. If any step fails, the process stops immediately.
​
Logging
automated
The process is fully logged. Use -v flags for more detailed output.
​
Idempotency
partial
Individual steps are idempotent, but the full sequence is designed for initial setup. Safe to re-run, but typically used only once.

​
Error Handling

If any step fails, the command will:
  1. Stop execution immediately
  2. Display an error message
  3. Exit with a non-zero status code
Common failure points:
  • No Git installed: Ensure Git is available in your PATH
  • Missing dependencies: Install system-level dependencies if required
  • Test failures: Fix any issues in generated test skeletons
This command is designed for new project setup. Running it on an existing project may overwrite certain files (though pyrig respects opt-out markers).

​
When to Use

Use init when

  • Setting up a brand new project
  • Converting a basic Python project to pyrig
  • You want a fully automated setup

Don't use init when

  • Updating an existing pyrig project (use mkroot instead)
  • You only need to regenerate configs
  • The project is already initialized
  • mkroot - Update configuration files only
  • mktests - Generate test skeletons only
  • mkinits - Create __init__.py files only

​
Implementation

The init command delegates to Pyrigger.I.init_project(), which orchestrates the entire initialization sequence. See pyrig/rig/cli/commands/init_project.py:9.
Run uv run pyrig init --help to see the command’s built-in help text.

Build docs developers (and LLMs) love

Get started for freeTalk to us