Step 1 - Installation & Environment

Install the Framework

Install ZCore with all its standard dependencies (FastAPI, SQLAlchemy, Pydantic, Questionary, Rich, etc.). The [all] extra ensures you get the complete toolkit.

pip install fastapi-zcore-framework[all]

Scaffold the Project with the CLI

Use the zc init command to create a project structure. The CLI will interactively ask for your database preference (SQLite, PostgreSQL, or MySQL) and package manager (uv or pip).

zc init task_manager && cd task_manager

This command automatically:

• Generates a pre-configured .env file with a freshly generated 64-character SECRET_KEY.
• Creates main.py, requirements.txt, and .gitignore.
• Initializes an isolated virtual environment (.venv) and installs project dependencies if selected.

Secret Keys & Environment Management

zc init already populates .env with a cryptographically strong SECRET_KEY. However, if you need to generate a new key or rotate credentials later, run:

zc gensecret

To generate a clean .env.example schema from your Pydantic settings at any time:

zc genenv -o .env.example -f

Understand the Settings Class

Open main.py. You will see that ZCore imports settings from zcore. This settings object is a SettingsProxy that reads from your .env file using Pydantic V2 Settings.

# main.py (excerpt)
from zcore import settings

# ZCore reads DATABASE_URL, SECRET_KEY, DEBUG, etc., automatically
print(settings.PROJECT_NAME)
print(settings.DATABASE.url)

In addition to core connectivity, all framework runtime boundaries are tunable via environment variables with sensible defaults:

# .env (Tunable framework parameters)
PAGINATION_DEFAULT_SIZE=20
PAGINATION_MAX_SIZE=100
SEARCH_MAX_DEPTH=3
AUTH_CACHE_TTL=300
CACHE_DEFAULT_TTL=3600
CACHE_LOCAL_MAXSIZE=1000
CACHE_EVICTION_INTERVAL=60
STREAM_QUEUE_MAXSIZE=100