Getting Started¶

Install FCube and create your first project.

Installation¶

Prerequisites¶

Python 3.9+ — Check with python --version
pip — Usually included with Python
Git — For version control
Docker — For containerized development (optional but recommended)

Option 1: Install from GitHub (Recommended)¶

# Using pip
pip install git+https://github.com/amal-babu-git/fcube.git

# Using uv (faster)
uv tool install git+https://github.com/amal-babu-git/fcube.git

Option 2: Install from Local Source¶

git clone https://github.com/amal-babu-git/fcube.git
cd fcube

# Install globally
pip install .

# Or install in editable mode for development
pip install -e .

# Using uv (recommended for development)
uv sync
source .venv/bin/activate

Option 3: Run Without Installation¶

git clone https://github.com/amal-babu-git/fcube.git
cd fcube

# Run using uv
uv run fcube --help

# Or using python module syntax
python -m fcube --help

Verify Installation¶

fcube --version
# FCube CLI v1.0.0

fcube --help

Create Your First Project¶

1. Generate Project¶

# Basic usage
fcube startproject MyApp

# Specify directory
fcube startproject MyApi --dir projects

# Without Celery
fcube startproject SimpleApi --no-celery

# Without Docker
fcube startproject LightApi --no-docker

# Force overwrite
fcube startproject MyProject --force

This creates:

my_project/
├── app/
│   ├── apis/
│   │   └── v1.py
│   └── core/
│       ├── __init__.py
│       ├── database.py
│       ├── models.py
│       ├── settings.py
│       ├── crud.py
│       ├── exceptions.py
│       ├── logging.py
│       ├── main.py
│       ├── dependencies.py
│       ├── alembic_models_import.py
│       └── celery_app.py
├── migrations/
├── docker/
│   ├── Dockerfile
│   └── docker-entrypoint.sh
├── docker-compose.yml
├── alembic.ini
├── pyproject.toml
├── .env.example
├── .gitignore
└── README.md

2. Set Up Environment¶

cd my_project

# Create virtual environment (optional if using Docker)
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: .\venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

3. Configure Database¶

# Copy example env
cp .env.example .env

# Edit .env with your database URL
# DATABASE_URL=postgresql://user:pass@localhost:5432/myapp

4. Run with Docker (Recommended)¶

# Start all services
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f

5. Run Migrations¶

# If using Docker
docker compose exec app alembic upgrade head

# If running locally
alembic upgrade head

6. Start the Server¶

# If using Docker
# Server is already running

# If running locally
uvicorn app.main:app --reload

Open http://localhost:8000/docs — you'll see the Swagger UI!

Add User Module¶

Add authentication and user management:

# Email/password authentication (default)
fcube adduser

# Phone OTP authentication
fcube adduser --auth-type phone

# Both email and phone authentication
fcube adduser --auth-type both

# Force overwrite
fcube adduser --force

This adds:

app/user/
├── __init__.py
├── models.py
├── schemas.py
├── crud.py
├── exceptions.py
├── auth_management/
│   ├── __init__.py
│   ├── routes.py
│   ├── service.py
│   └── utils.py
├── permission_management/
│   ├── __init__.py
│   ├── utils.py
│   └── scoped_access.py
└── services/
    ├── __init__.py
    └── user_referral_integration.py

Add a Plugin¶

Plugins add pre-built features to your project:

# List available plugins
fcube addplugin --list

# Preview plugin (dry run)
fcube addplugin referral --dry-run

# Install plugin
fcube addplugin referral

# Force overwrite
fcube addplugin referral --force

Learn more in the Plugin System guide.

Create a Custom Module¶

# Basic usage
fcube startmodule product

# Without admin routes
fcube startmodule review --no-admin

# Without public routes
fcube startmodule internal_report --no-public

# Force overwrite
fcube startmodule product --force

This generates:

app/product/
├── __init__.py
├── dependencies.py
├── exceptions.py
├── permissions.py
├── tasks.py
├── README.md
├── models/
│   ├── __init__.py
│   └── product.py
├── schemas/
│   ├── __init__.py
│   └── product_schemas.py
├── crud/
│   ├── __init__.py
│   └── product_crud.py
├── services/
│   ├── __init__.py
│   └── product_service.py
├── routes/
│   ├── __init__.py
│   ├── public/
│   │   ├── __init__.py
│   │   └── product.py
│   └── admin/
│       ├── __init__.py
│       └── product_management.py
├── utils/
│   └── __init__.py
└── integrations/
    └── __init__.py

Add Entity to Module¶

Add a new entity to an existing module:

fcube addentity service_provider availability

fcube addentity booking payment --force

List Modules¶

fcube listmodules

fcube listmodules --dir app

Shows all existing modules with their structure.

Next Steps¶

Learn the commands — See Commands Reference
Understand the architecture — Read Generated Architecture
Explore plugins — Check Plugin System
Deploy your app — Use the deploy-vps plugin

Common Issues¶

Can't connect to database¶

# Check PostgreSQL is running
pg_isready

# Verify DATABASE_URL format
postgresql://user:password@host:port/database

Module not found after generation¶

# Ensure you're in virtual environment
source venv/bin/activate

# Reinstall in development mode
pip install -e .

Migrations fail¶

# Check alembic.ini has correct sqlalchemy.url
# Or set env variable and run:
alembic upgrade head