Stop setting up boilerplate from scratch. Launch your next production-ready Python project in seconds with zero configuration.

---

✨ Features

• 💻 Interactive CLI Interface — Elegant, user-friendly interactive prompt powered by questionary and styled with rich.
• 📦 Package Manager Selection — Choose between pip, uv, or Poetry to manage project dependencies automatically.
• ⚡ Framework Support — FastAPI, Flask, Django, Litestar, Sanic, and Masonite templates out-of-the-box.
• 🏗️ Professional Backend Structure — Generate comprehensive production-ready layouts that separate configuration, routing, schemas, and databases.
• 🔑 Authentication Integration — Pre-configured JWT or OAuth2 flows for FastAPI, Flask, and Django backends.
• 🗄️ Interactive Database Auto-Setup — Choose SQLite, PostgreSQL, or MySQL; dependencies and environment variables get configured automatically.
• ⚛️ Frontend Pairing — Bootstrap a Vite React/Vue 3/Svelte or Next.js App Router frontend alongside your backend automatically with a gorgeous, dark-themed premium landing page.
• 📂 Multi-folder Generation — Generates separate backend/ and frontend/ directories at the workspace root when pairing backend and frontend, and sets up root orchestration files (docker-compose.yml, README.md, .gitignore).
• 🤖 AI-Powered Templates — Initialize custom structures based on conversational prompts using Google Gemini.
• 🐳 Docker Ready — Fully-featured multi-stage Dockerfile configurations included automatically.
• ⚙️ Zero Boilerplate — Get linting, testing, and dependency configurations setup automatically.

---

📦 Installation

To get started, install setupci from PyPI using pip:

pip install setupci

🔄 Keep Up-to-date

Upgrade to the latest version to get the newest features and templates:

pip install --upgrade setupci

---

🚀 Usage

Navigate to your workspace and initialize a new project in the current directory (or specify a subfolder):

setupci init .

🔄 Interactive Workflow

Once the CLI starts, it walks you through your project choices:

1. Framework Selection — Choose between FastAPI, Flask, Django, Litestar, Sanic, Masonite, or General Python.
2. Package Manager Selection — Choose between pip (with requirements.txt), uv, or Poetry.
3. Project Type Selection —
   • Backend: Generates a professional structure with Docker configurations, databases, linting, and CRUD examples.
   • Simple: A streamlined single-file entrypoint ideal for quick scripts or lightweight services.
4. Database Selection (Only for Backend types) — Choose between SQLite, PostgreSQL, or MySQL.
5. Authentication Selection (Only for FastAPI, Flask, and Django Backend types) — Select None, JWT, or OAuth2 flows.
6. Frontend Selection (Only for Backend types) — Choose None, React, Vue, Svelte, or Next.js.

📝 Note: If a frontend is selected, setupci will generate separate backend/ and frontend/ directories in your workspace, plus root-level docker-compose.yml, .gitignore, and README.md files to run both services together easily.

---

💻 Terminal Demo

Below is an example of what running setupci init looks like in your terminal:

$ setupci init .

 ███████╗███████╗████████╗██╗   ██╗██████╗  ██████╗██╗
 ██╔════╝██╔════╝╚══██╔══╝██║   ██║██╔══██╗██╔════╝██║
 ███████╗█████╗     ██║   ██║   ██║██████╔╝██║     ██║
 ╚════██║██╔══╝     ██║   ██║   ██║██╔═══╝ ██║     ██║
 ███████║███████╗   ██║   ╚██████╔╝██║     ╚██████╗██║
 ╚══════╝╚══════╝   ╚═╝    ╚═════╝ ╚═╝      ╚═════╝╚═╝

                 Python Project Bootstrapper  •  v0.2.0

┌────────────────────────────── 🚀 Getting Started ──────────────────────────────┐
│ Answer a few questions and your project structure will be ready in seconds.      │
└──────────────────────────────────────────────────────────────────────────────────┘

? Which framework would you like to use? FastAPI
? Which package manager would you like to use? uv
? Which project type would you like? Backend
? Which database would you like to configure? PostgreSQL
? Would you like to add Authentication? JWT
? Would you like to pair this backend with a frontend? Next.js

┌──────────────────────────────── 📋 Project Summary ───────────────────────────────┐
│  Framework:        FastAPI                                                      │
│  Package Manager:  uv                                                           │
│  Type:             Backend                                                      │
│  Database:         PostgreSQL                                                   │
│  Auth:             JWT                                                          │
│  Frontend:         Next.js                                                      │
│  Location:         E:\my-new-project                                            │
└──────────────────────────────────────────────────────────────────────────────────┘

⠋ Generating project files...
✓ Your FastAPI backend project is ready!

---

🗂️ Generated Structures

setupci designs clean layouts adhering to industry standards. Here is what gets generated:

⚡ FastAPI — Backend

A clean modular design using Pydantic, SQLAlchemy, and dependency injection.

app/
├── main.py                # App entrypoint with middleware, routing, & setup
├── core/
│   └── config.py          # Settings management loading configs from .env using Pydantic
├── api/
│   ├── router.py          # Global API router aggregating separate endpoints
│   └── endpoints/
│       └── items.py       # Implements complete mock CRUD endpoints (GET, POST, etc.)
├── models/
│   └── item.py            # SQLAlchemy Database model definitions
├── schemas/
│   └── item.py            # Pydantic schemas validating API payloads
└── db/
    └── session.py         # DB connection setup and SessionLocal generator
requirements.txt           # Main API dependencies
Dockerfile                 # Multi-stage Docker build config
.env.example               # Template database and system environment variables

🌶️ Flask — Backend

A structure implementing the flask factory pattern, Blueprints, and Flask-SQLAlchemy.

app/
├── __init__.py            # Application factory setup & extension loading
├── config.py              # Configuration classes (Development, Production)
├── api/
│   └── items.py           # Blueprint definition mapping API routes
└── models/
    └── item.py            # Database model mapping using Flask-SQLAlchemy
wsgi.py                    # Entry point script to run the server
requirements.txt           # Web server, Flask, and DB drivers
Dockerfile                 # Gunicorn-based production Docker setup
.env.example               # Flask configurations template

🎸 Django — Backend

A modernized Django layout splitting apps, tracking settings with django-environ, and API-ready with DRF.

config/
├── settings.py            # Core settings reading environment values from .env
├── urls.py                # Main URL configurations
├── wsgi.py                # WSGI entrypoint for web servers
└── asgi.py                # ASGI entrypoint for async channels or servers
apps/
└── items/                 # Pre-configured DRF API App
    ├── models.py          # Sample DB model definitions
    ├── views.py           # REST views implementing ModelViewSet
    ├── serializers.py     # Serializers converting model data to JSON
    └── urls.py            # App-level routing definitions
manage.py                  # Django execution utility
requirements.txt           # Django + DRF and dependencies
Dockerfile                 # Lightweight container setup for deployment
.env.example               # Configurable Django secret key and DB environment settings

🐍 General Python — Backend

A standard workspace ready for library publication or tool development.

src/
├── __init__.py            # Main package initializer
└── main.py                # Main execution script
tests/
└── test_main.py           # Standard pytest script
pyproject.toml             # Modern setup configuration for packaging/publishing
README.md                  # Basic user guide for the created package

⚛️ Fullstack Layout (Backend + Frontend)

When pairing a backend with a frontend (e.g. Next.js, React, Vue, Svelte), a clean separated structure is generated.

my-project/
├── backend/               # Backend API project (FastAPI, Flask, Django, etc.)
│   ├── app/               # Source code
│   ├── Dockerfile         # Backend container config
│   └── requirements.txt   # Python dependencies
├── frontend/              # Frontend web application (Next.js, React, Vue, Svelte)
│   ├── app/ or src/       # Frontend UI pages & components
│   ├── package.json       # JS dependencies & scripts
│   └── README.md          # Setup guide
├── docker-compose.yml     # Orchestrates both services for easy local execution
├── .gitignore             # Root-level ignore entries
└── README.md              # Root setup instructions

---

❔ Why setupci?

Developers spend too much time repeating the same boilerplate setups. setupci bridges this gap:

• 🕒 Saves Time: Avoid copying config files, writing database connections, or creating dockerfiles. Get to coding in 5 seconds.
• 🛡️ Production-Ready: Implements industry best-practices such as configuration-code separation, factory patterns, environment variables, and Docker containerization.
• 🔰 Beginner & Pro Friendly: Gives beginners a clear architecture to build on, and professionals a consistent, zero-fluff starter template.

---

🗺️ Roadmap

We are constantly improving setupci. Check out our planned roadmap:

• Database Scaffolding — Auto-configure SQLite, PostgreSQL, or MySQL (MongoDB/others planned).
• Authentication Integration — Bootstrap JWT/OAuth2 flows out-of-the-box.
• AI-Powered Templates — Prompt-to-structure project initialization.
• Full-stack Support — Pair backend frameworks with React, Vue, or Svelte frontends.
• Extended Frameworks — Support for Litestar, Sanic, and Masonite.
• Extended Authentication — Support for Auth0, Cognito, and Firebase Auth.

---

🤝 Contributing

Contributions make the open-source community an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

Please see our CONTRIBUTING.md to understand details on submitting PRs, setting up local tests, and reporting bugs.

---

📝 License

Distributed under the MIT License. See LICENSE for more information.

---

🔗 Links

• 🐙 GitHub Repository: github.com/syed-mujtaba-stack/setupci
• 📦 PyPI Package: pypi.org/project/setupci
• 🐛 Issues & Requests: github.com/syed-mujtaba-stack/setupci/issues