CLI Reference

Complete reference for all FastAPI-fastkit command-line interface commands.

Global Options

All commands support these global options:

$ fastkit [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS]

Global Options

Option	Description
--version	Show FastAPI-fastkit version
--help	Show help message

Examples

$ fastkit --version
FastAPI-fastkit version 1.0.0

$ fastkit --help
Usage: fastkit [OPTIONS] COMMAND [ARGS]...

  FastAPI-fastkit CLI

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  addroute       Add a new route to FastAPI project
  init           Create a new FastAPI project
  list-templates List available FastAPI templates
  runserver      Start FastAPI development server
  startdemo      Create FastAPI project from template

Commands

init

Create a new FastAPI project with interactive setup.

Syntax

$ fastkit init [OPTIONS]

Options

Option	Description	Default
--package-manager	Package manager to use (pip, uv, pdm, poetry)	uv
--help	Show command help	-

Interactive Prompts

The init command will prompt you for:

1. Project name: Directory name and package name
2. Author name: Package author information
3. Author email: Contact email for package
4. Project description: Brief description of the project
5. Stack selection: Choose from minimal, standard, or full
6. Package manager selection: Choose from pip, uv, pdm, or poetry (unless specified with --package-manager)

Stack Options

MINIMAL Stack:

• fastapi - FastAPI framework
• uvicorn - ASGI server
• pydantic - Data validation
• pydantic-settings - Configuration management

STANDARD Stack:

• All MINIMAL stack packages
• sqlalchemy - SQL toolkit and ORM
• alembic - Database migration tool
• pytest - Testing framework

FULL Stack:

• All STANDARD stack packages
• redis - In-memory data store
• celery - Distributed task queue

Examples

$ fastkit init
Enter the project name: my-api
Enter the author name: John Doe
Enter the author email: john@example.com
Enter the project description: My awesome API

Select stack (minimal, standard, full): standard
Select package manager (pip, uv, pdm, poetry) [uv]: uv
Do you want to proceed with project creation? [y/N]: y

✨ FastAPI project 'my-api' has been created successfully!

Generated Structure

Creates a project with this structure:

my-api/
├── .venv/                    # Virtual environment
├── src/
│   ├── __init__.py
│   ├── main.py              # FastAPI application
│   ├── core/
│   │   ├── __init__.py
│   │   └── config.py        # Configuration
│   ├── api/
│   │   ├── __init__.py
│   │   ├── api.py          # API router collection
│   │   └── routes/
│   │       ├── __init__.py
│   │       └── items.py     # Example route
│   ├── crud/
│   │   ├── __init__.py
│   │   └── items.py         # CRUD operations
│   ├── schemas/
│   │   ├── __init__.py
│   │   └── items.py         # Pydantic schemas
│   └── mocks/
│       ├── __init__.py
│       └── mock_items.json  # Test data
├── tests/
├── scripts/
├── requirements.txt
├── setup.py
└── README.md

addroute

Add a new API route to an existing FastAPI project.

Syntax

$ fastkit addroute ROUTE_NAME [PROJECT_DIR] [OPTIONS]

Arguments

Argument	Description	Required
ROUTE_NAME	Name of the new route (plural recommended)	Yes
PROJECT_DIR	Project directory under your workspace (defaults to ., the current directory)	No

Options

Option	Description	Default
--help	Show command help	-

Examples

$ cd my-api
$ fastkit addroute users
                       Adding New Route
┌──────────────────┬──────────────────────────────────────────┐
│ Project          │ my-api                                   │
│ Route Name       │ users                                    │
│ Target Directory │ ~/my-api                                 │
└──────────────────┴──────────────────────────────────────────┘

Do you want to add route 'users' to project 'my-api'? [Y/n]: y

✨ Successfully added new route 'users' to project 'my-api'

You can also target a project under your workspace by name without cd-ing into it:

$ fastkit addroute users my-api

Generated Files

Creates these files in the project:

• src/api/routes/users.py - Route handlers
• src/crud/users.py - CRUD operations
• src/schemas/users.py - Pydantic schemas

Also updates src/api/api.py to include the new router.

Generated Endpoints

Creates full CRUD endpoints:

Method	Endpoint	Description
GET	/api/v1/users/	Get all users
POST	/api/v1/users/	Create new user
GET	/api/v1/users/{user_id}	Get specific user
PUT	/api/v1/users/{user_id}	Update user
DELETE	/api/v1/users/{user_id}	Delete user

startdemo

Create a FastAPI project from a pre-built template.

Syntax

$ fastkit startdemo [OPTIONS]

Options

Option	Description	Default
--package-manager	Package manager to use (pip, uv, pdm, poetry)	uv
--help	Show command help	-

Interactive Prompts

The startdemo command will prompt you for:

1. Project name: Directory name for the new project
2. Author name: Package author information
3. Author email: Contact email
4. Project description: Brief description
5. Package manager selection: Choose from pip, uv, pdm, or poetry (unless specified with --package-manager)

Available Templates

Template	Description	Features
fastapi-default	Simple FastAPI Project	Basic CRUD, Mock data
fastapi-async-crud	Async Item Management API	Async/await, Performance
fastapi-custom-response	Custom Response System	Custom responses, Pagination
fastapi-dockerized	Dockerized FastAPI API	Docker, Production ready
fastapi-psql-orm	PostgreSQL FastAPI API	PostgreSQL, SQLAlchemy, Alembic
fastapi-empty	Minimal FastAPI Project	Bare minimum setup

Examples

$ fastkit startdemo fastapi-psql-orm
Enter the project name: my-blog
Enter the author name: Jane Smith
Enter the author email: jane@example.com
Enter the project description: Blog API with PostgreSQL

Select package manager (pip, uv, pdm, poetry) [uv]: poetry
Do you want to proceed with project creation? [y/N]: y

✨ FastAPI project 'my-blog' from 'fastapi-psql-orm' has been created!

runserver

Start the FastAPI development server.

Syntax

$ fastkit runserver [OPTIONS]

Options

Option	Short	Description	Default
--host	-h	Host to bind to	127.0.0.1
--port	-p	Port to bind to	8000
--reload	-r	Enable auto-reload	True
--workers	-w	Number of workers	1
--help		Show command help	-

Examples

# Basic usage (default settings)
$ fastkit runserver
INFO:     Uvicorn running on http://127.0.0.1:8000

# Custom host and port
$ fastkit runserver --host 0.0.0.0 --port 8080
INFO:     Uvicorn running on http://0.0.0.0:8080

# Disable auto-reload
$ fastkit runserver --no-reload
INFO:     Uvicorn running on http://127.0.0.1:8000

# Multiple workers (production)
$ fastkit runserver --workers 4
INFO:     Uvicorn running on http://127.0.0.1:8000

Requirements

• Must be run from a FastAPI project directory
• Project must have src/main.py with FastAPI app
• Virtual environment should be activated

list-templates

List all available FastAPI project templates.

Syntax

$ fastkit list-templates [OPTIONS]

Options

Option	Description	Default
--help	Show command help	-

Examples

$ fastkit list-templates
                      Available Templates
┌─────────────────────────┬───────────────────────────────────┐
│ fastapi-custom-response │ Async Item Management API with    │
│                         │ Custom Response System            │
│ fastapi-dockerized      │ Dockerized FastAPI Item           │
│                         │ Management API                    │
│ fastapi-empty           │ No description                    │
│ fastapi-async-crud      │ Async Item Management API Server  │
│ fastapi-psql-orm        │ Dockerized FastAPI Item           │
│                         │ Management API with PostgreSQL    │
│ fastapi-default         │ Simple FastAPI Project            │
└─────────────────────────┴───────────────────────────────────┘

Environment Variables

FastAPI-fastkit respects these environment variables:

Variable	Description	Default
FASTKIT_CONFIG_DIR	Configuration directory	~/.fastkit
FASTKIT_TEMPLATES_DIR	Custom templates directory	Built-in templates
FASTKIT_LOG_LEVEL	Logging level	INFO

Examples

# Custom configuration directory
$ export FASTKIT_CONFIG_DIR=~/my-fastkit-config
$ fastkit init

# Custom templates directory
$ export FASTKIT_TEMPLATES_DIR=~/my-templates
$ fastkit list-templates

# Debug logging
$ export FASTKIT_LOG_LEVEL=DEBUG
$ fastkit init

Configuration Files

FastAPI-fastkit can use configuration files for default settings.

Configuration File Location

1. $FASTKIT_CONFIG_DIR/config.yaml (if FASTKIT_CONFIG_DIR is set)
2. ~/.fastkit/config.yaml (default)
3. ./fastkit.yaml (project-specific)

Configuration Format

# ~/.fastkit/config.yaml
default:
  author:
    name: "Your Name"
    email: "your.email@example.com"

  project:
    stack: "standard"
    create_venv: true
    install_deps: true

  server:
    host: "127.0.0.1"
    port: 8000
    reload: true

templates:
  custom_dir: "~/my-templates"

logging:
  level: "INFO"
  file: "~/.fastkit/logs/fastkit.log"

Common Workflows

1. Create New Project

# Create a new project
$ fastkit init
# Follow prompts...

# Navigate to project
$ cd my-awesome-api

# Activate virtual environment
$ source .venv/bin/activate

# Start development server
$ fastkit runserver

2. Add Features to Existing Project

# Add multiple routes (project name as second positional arg = workspace project)
$ fastkit addroute users my-api
$ fastkit addroute products my-api
$ fastkit addroute orders my-api

# Test the API
$ fastkit runserver
# Visit http://127.0.0.1:8000/docs

3. Use Templates for Complex Projects

# List available templates
$ fastkit list-templates

# Create from template
$ fastkit startdemo
# Select fastapi-psql-orm for database project

# Setup database (for PostgreSQL template)
$ cd my-project
$ docker-compose up -d postgres
$ source .venv/bin/activate
$ alembic upgrade head
$ fastkit runserver

Troubleshooting

Command Not Found

If fastkit command is not found:

1. Check installation:
   

   $ pip show fastapi-fastkit
   

2. Reinstall if needed:
   

   $ pip uninstall fastapi-fastkit
   $ pip install fastapi-fastkit
   

3. Check PATH:
   

   $ which fastkit
   

Virtual Environment Issues

If virtual environment creation fails:

1. Check Python version:
   

   $ python --version  # Should be 3.12+
   

2. Check venv module:
   

   $ python -m venv --help
   

3. Manual virtual environment:
   

   $ python -m venv .venv
   $ source .venv/bin/activate
   $ pip install -r requirements.txt
   

Server Won't Start

If fastkit runserver fails:

1. Check you're in project directory
2. Verify src/main.py exists

3. Activate virtual environment:
   

   $ source .venv/bin/activate
   

4. Check for syntax errors:
   

   $ python -c "from src.main import app"
   

Port Already in Use

If port 8000 is busy:

# Use different port
$ fastkit runserver --port 8080

# Or kill existing process
$ lsof -ti:8000 | xargs kill -9

Advanced Usage

Custom Templates

You can create custom templates by:

1. Creating template directory:

   my-template/
   ├── src/
   │   └── main.py-tpl
   ├── requirements.txt-tpl
   └── setup.py-tpl
   

2. Setting environment variable:
   

   $ export FASTKIT_TEMPLATES_DIR=~/my-templates
   

3. Using custom template:
   

   $ fastkit startdemo
   # Your custom templates will appear in the list
   

Scripting with FastAPI-fastkit

You can use FastAPI-fastkit in scripts:

#!/bin/bash
# create-microservices.sh

for service in users products orders; do
    echo "Creating $service service..."
    fastkit init <<EOF
$service-service
Company Team
team@company.com
$service microservice
minimal
y
EOF

    cd "$service-service"
    fastkit addroute "$service"
    cd ..
done

Integration with CI/CD

Example GitHub Actions workflow:

name: Test FastAPI-fastkit Project

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2

    - name: Set up Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.12'

    - name: Install FastAPI-fastkit
      run: pip install fastapi-fastkit

    - name: Create test project
      run: |
        fastkit init <<EOF
        test-project
        CI
        ci@example.com
        Test project
        standard
        y
        EOF

    - name: Test project
      run: |
        cd test-project
        source .venv/bin/activate
        python -m pytest

Package Manager Support

FastAPI-fastkit supports multiple Python package managers, allowing you to choose the one that best fits your workflow.

Supported Package Managers

Manager	Description	Dependency File	Best For
UV (default)	Fast Python package manager	pyproject.toml	Speed and performance
PDM	Modern Python dependency management	pyproject.toml	Advanced dependency resolution
Poetry	Python dependency management and packaging	pyproject.toml	Poetry-based workflows
PIP	Standard Python package manager	requirements.txt	Traditional Python development

Specifying Package Manager

Global Configuration

You can set your preferred package manager for all projects:

# Using command line options
$ fastkit init --package-manager poetry
$ fastkit startdemo --package-manager pdm

Project-specific Selection

Each project can use a different package manager. The choice is made during project creation and affects:

• Dependency file format: Each manager creates its appropriate files
• Virtual environment management: Different activation methods
• Dependency installation: Manager-specific commands

Package Manager Features

UV (Default)

• Fast: Rust-based, extremely fast dependency resolution
• Compatible: Drop-in replacement for pip and pip-tools
• Modern: Support for PEP 621 project metadata

$ fastkit init --package-manager uv
# Creates pyproject.toml with UV configuration

PDM

• Modern: PEP 582 and PEP 621 support
• Advanced: Sophisticated dependency resolution
• Flexible: Multiple project layouts

$ fastkit init --package-manager pdm
# Creates pyproject.toml with PDM configuration

Poetry

• Established: Mature and widely adopted
• Integrated: Build and publish support
• Lockfile: poetry.lock for reproducible builds

$ fastkit init --package-manager poetry
# Creates pyproject.toml with Poetry configuration

PIP

• Standard: Built into Python
• Compatible: Works everywhere
• Simple: Straightforward dependency management

$ fastkit init --package-manager pip
# Creates requirements.txt

Working with Projects

After creating a project with a specific package manager:

UV Projects

cd my-project
uv sync          # Install dependencies
uv add requests  # Add new dependency
uv run pytest   # Run commands in environment

PDM Projects

cd my-project
pdm install      # Install dependencies
pdm add requests # Add new dependency
pdm run pytest  # Run commands in environment

Poetry Projects

cd my-project
poetry install      # Install dependencies
poetry add requests # Add new dependency
poetry run pytest  # Run commands in environment

PIP Projects

cd my-project
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows
pip install -r requirements.txt
pip install requests
pytest

Next Steps

Now that you understand the CLI:

1. Quick Start: Try the commands hands-on
2. Your First Project: Build a complete application
3. Contributing: Contribute to FastAPI-fastkit

CLI Tips

• Use --help with any command for detailed help
• Configure default settings to speed up project creation
• Use templates for complex project setups
• Combine commands to create powerful workflows