Proto Craft

A CLI tool for rapidly creating and managing development projects with FastAPI boilerplate templates and modular app structures.

Overview

Proto Craft streamlines the process of scaffolding new FastAPI-based projects and creating self-contained app modules within those projects. It provides automated setup with configurable Python versions and maintains a clean directory structure.

Features

• 🚀 Project Creation: Clone and initialize FastAPI boilerplate projects
• 📦 App Scaffolding: Create modular app structures with predefined file templates
• 🔍 Project Inspection: Verify app structure and create missing files
• 🐍 Python Version Control: Support for Python 3.10 - 3.15
• 📋 Configuration Management: builder.ini-based project configuration

Installation

Prerequisites

• Python >= 3.12
• Git
• uv package manager (recommended)

From Source

git clone https://github.com/tinspj1997/proto-craft.git
cd proto-craft
uv sync

Install as Package

pip install proto-craft
# or with uv
uv pip install proto-craft

Quick Start

Create a New Project

proto-craft create project

Follow the interactive prompts:

• Enter your project name
• Specify the required Python version (3.10-3.15, default: 3.12)

The tool will:

1. Clone the FastAPI boilerplate repository
2. Remove the .git directory for a fresh start
3. Create builder.ini configuration
4. Set up .python-version file

Navigate to Your Project

cd your-project-name
uv sync

Create an App Inside the Project

proto-craft create app

Provide the app name when prompted. This creates:

src/app/your-app-name/
├── __init__.py
├── routes.py
├── schema.py
└── service.py

Inspect Project Apps

Verify the structure of all apps in your project:

proto-craft inspect

Create missing files automatically:

proto-craft inspect --add

Display Version

proto-craft version

Configuration

builder.ini

Located in the project root, contains project metadata:

[project]
name = your-project-name
version = 1.0.0
python_version = 3.12
app_path = src/app

• app_path: Directory where new apps are created (relative to project root)

.python-version

Specifies the project's Python version for tools like pyenv or uv.

Project Structure

your-project-name/
├── .python-version          # Python version specification
├── builder.ini              # Project configuration
├── src/
│   └── app/
│       └── your-app-name/   # New apps created here
│           ├── __init__.py
│           ├── routes.py
│           ├── schema.py
│           └── service.py
├── main.py
└── [other project files]

Environment Variables

PROTO_CRAFT_PASSKEY

Optional environment variable for authentication:

export PROTO_CRAFT_PASSKEY="your-passkey"
proto-craft create project

If not set, you'll be prompted for the passkey interactively.

Development

Requirements

• Python 3.12+
• Dependencies: typer, rich

Install Development Dependencies

cd proto-craft
uv sync --all-extras

Run Commands

# Development mode
uv run proto-craft --help

# Or install in editable mode
pip install -e .
proto-craft --help

Troubleshooting

builder.ini not found

Ensure you're running commands from the project root directory created by the tool.

cd /path/to/your/project
proto-craft inspect

app_path not configured

Edit your builder.ini and verify the [project] section contains an app_path entry.

Git clone fails

• Check your internet connection
• Verify the repository URL in instructions.py
• Ensure git is installed and accessible

Python version validation error

Specify a Python version between 3.10 and 3.15:

proto-craft create project
# When prompted: Enter a version like 3.12

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with proper type hints
4. Run tests (when available)
5. Submit a pull request

License

See LICENSE file in the repository.

Author

Tins P Joseph

• Email: tinspj1997@gmail.com
• GitHub: @tinspj1997

Related Projects

• FastAPI Boilerplate - The template used for project creation

Support

For issues, questions, or suggestions:

• 📝 Open an issue on GitHub
• 📧 Email the author
• 💬 Check existing documentation

---

Last Updated: March 2025
Version: 0.1.0