fastgear-cli 0.2.1
CLI tool for generating FastAPI boilerplate code using the Fastgear library
Requires Python: >=3.13

# FastGear CLI
[![codecov](https://codecov.io/gh/hmarcuzzo/fastgear-cli/graph/badge.svg?token=0QNZTA5332)](https://codecov.io/gh/hmarcuzzo/fastgear-cli)
[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A powerful CLI tool to bootstrap **FastAPI** projects powered by the [FastGear](https://github.com/hmarcuzzo/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](https://github.com/hmarcuzzo/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](https://docs.astral.sh/uv/) (recommended for dependency management)

## 🔧 Installation

### Using uv (recommended)

```bash
uv pip install fastgear-cli
```

### Using pip

```bash
pip install fastgear-cli
```

### From source

```bash
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:

```bash
fg init
```

Create a project in a specific directory:

```bash
fg init /path/to/project
```

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

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

## 📖 Usage Examples

### Basic Project Creation

```bash
$ 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:

```bash
$ 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:

```bash
fg init ~/projects/new-api
```


## 🎯 Commands

### `init`

Initialize a new FastAPI project with FastGear.

**Usage:**
```bash
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)


## 📝 License

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