FastGear CLI

---

A powerful CLI tool to bootstrap FastAPI projects powered by the FastGear library — with best practices, pre-configured templates, and modern development tools out of the box.

---

🎯 What is FastGear CLI?

FastGear CLI is the official command-line companion for the FastGear library. It streamlines the creation of FastAPI projects by generating a complete, production-ready project structure with:

• Pre-configured FastGear integration for accelerated API development
• FastAPI application scaffolding with best practices
• Modern Python project setup with type hints and validation

Note: Projects generated by FastGear CLI are designed to work seamlessly with the FastGear library, which provides utilities, patterns, and abstractions to supercharge your FastAPI development.

✨ Features

• 🚀 FastAPI Project Setup - Create production-ready FastAPI projects in seconds
• ⚡ FastGear Integration - Pre-configured to use the FastGear library
• 🐳 Docker Support - Optional Docker configuration with Dockerfile and docker-compose
• 🤖 AI Agent Tools - Integrate AI-powered development tools (GitHub Copilot)
• 🔄 CI/CD Integration - Pre-configured CI/CD pipelines (GitHub Actions)
• 📦 Modern Dependencies - Uses uv for fast, reliable dependency management
• 🔍 Dry-Run Mode - Preview files before creation
• ✅ Type-Safe - Full type hints and Pydantic models
• 🧪 Test Coverage - Comprehensive test suite with pytest

📋 Requirements

• Python 3.13+
• uv (recommended for dependency management)

🔧 Installation

Using uv (recommended)

uv pip install fastgear-cli

Using pip

pip install fastgear-cli

From source

git clone https://github.com/hmarcuzzo/fastgear-cli.git
cd fastgear-cli
uv pip install -e .

🚀 Quick Start

Create a new project in the current directory:

fg init

Create a project in a specific directory:

fg init /path/to/project

Preview what files would be created (dry-run):

fg init --dry-run
# or
fg init -n

📖 Usage Examples

Basic Project Creation

$ fg init

? Project name: my-awesome-api
? Project title: My Awesome API
? Use Docker? Yes
? Use AI agent tools? No
? Use CI/CD pipeline? Yes
? Select CI/CD provider: GitHub Actions

📦 Generating uv.lock...
🎉  Project 'my-awesome-api' created successfully!

Your new FastAPI project is ready with FastGear pre-configured!

Dry-Run Mode

Preview the project structure before creating files:

$ fg init --dry-run

? Project name: my-awesome-api
? Project title: My Awesome API
? Use Docker? Yes

🔍 Dry run mode - no files created

Files that would be created:
└── 📁 my-awesome-api
    ├── 📁 docker
    │   ├── 📄 Dockerfile
    │   └── 📄 docker-compose.yml
    ├── 📁 src
    │   └── 📁 my_awesome_api
    │       ├── 📄 __init__.py
    │       └── 📄 main.py          # FastAPI app with FastGear
    ├── 📁 tests
    │   ├── 📄 __init__.py
    │   └── 📄 test_main.py
    ├── 📄 .dockerignore
    ├── 📄 .gitignore
    ├── 📄 pyproject.toml           # Includes FastGear dependency
    └── 📄 README.md

Total: 12 file(s)

Custom Directory

Create a project in a specific location:

fg init ~/projects/new-api

Add Components to an Existing Module

Create an entity:

fg add entity user --path src/modules/user

Create a service and inject a repository explicitly:

fg add service user --path src/modules/user \
  --repository-path src.modules.user.repositories.UserRepository

Create a repository and choose interactively whether to inject an entity:

fg add repository user --path src/modules/user

Create a full module and choose components interactively:

fg add module user --path src/modules

Create a module non-interactively:

fg add module user --path src/modules \
  --module-components entity,repository,service,controller

Preview created files without writing:

fg add module user --path src/modules --module-components service,controller --dry-run

🎯 Commands

init

Initialize a new FastAPI project with FastGear.

Usage:

fg init [DIRECTORY] [OPTIONS]

Arguments:

• DIRECTORY - Target directory (default: current directory)

Options:

• --dry-run, -n - Show what files would be created without creating them
• --help - Show help message

Interactive Prompts:

1. Project name - The name of your project (used for directory and package names)
2. Project title - Human-readable project title
3. Use Docker? - Include Docker configuration files
4. Use AI agent tools? - Include AI development tools configuration
5. Use CI/CD pipeline? - Include continuous integration/deployment setup
6. Select CI/CD provider - Choose your CI/CD platform (if enabled)

add

Add components to an existing project/module.

Usage:

fg add [ELEMENT_TYPE] [ELEMENT_NAME] [OPTIONS]

Element types:

• entity
• repository
• service
• controller
• module

Arguments:

• ELEMENT_TYPE - Component type to generate
• ELEMENT_NAME - Component/module name (normalized to snake_case)

Common options:

• --path, -p - Base directory where files are generated (default: current directory)
• --use-folders/--no-use-folders - Generate in folders (entities/, services/, etc.) or flat files
• --dry-run, -n - Preview output without writing files

Dependency options:

• --entity-path - Entity import path used by repository
• --repository-path - Repository import path used by service
• --service-path - Service import path used by controller

Module option:

• --module-components - Comma-separated list for module: entity,repository,service,controller

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.