Metadata-Version: 2.4
Name: fastgear-cli
Version: 0.5.1
Summary: CLI tool for generating FastAPI boilerplate code using the Fastgear library
Author-email: Henrique Marcuzzo <henrique.souza.m06@gmail.com>
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: jinja2>=3.1.6
Requires-Dist: pydantic>=2.12.5
Requires-Dist: questionary>=2.1.1
Requires-Dist: typer>=0.21.1
Description-Content-Type: text/markdown

<div align="center">
<h1>FastGear CLI</h1>

<a href="https://github.com/hmarcuzzo/fastgear-cli" target="_blank">
    <img src="https://img.shields.io/badge/Python-3.13 | 3.14-40cd60" alt="Supported Python Versions"/>
</a>
<a href="https://pypi.org/project/fastgear-cli/" target="_blank">
    <img src="https://img.shields.io/pypi/v/fastgear-cli?color=%2334D058&label=pypi%20package" alt="PyPi Version"/>
</a>
<a href="https://github.com/hmarcuzzo/fastgear-cli/actions/workflows/tests.yaml" target="_blank">
    <img src="https://github.com/hmarcuzzo/fastgear-cli/actions/workflows/tests.yaml/badge.svg" alt="Tests">
</a>
<a href="https://codecov.io/gh/hmarcuzzo/fastgear-cli" target="_blank">
    <img src="https://codecov.io/gh/hmarcuzzo/fastgear-cli/graph/badge.svg?token=0QNZTA5332" alt="codecov">
</a>

<hr>
A powerful CLI tool to bootstrap <strong>FastAPI</strong> projects powered by the <a href="https://github.com/hmarcuzzo/fastgear">FastGear</a> library — with best practices, pre-configured templates, and modern development tools out of the box.
<hr>
</div>

## 🎯 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
```

### Add Components to an Existing Module

Create an entity:

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

Create a service and inject a repository explicitly:

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

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

Create a full module and choose components interactively:

```bash
fg add module user --path src/modules
```

Create a module non-interactively:

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

Preview created files without writing:

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

## 🎯 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)

### `add`

Add components to an existing project/module.

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