How to use CLI commands

Master the ZCore interactive CLI for project scaffolding, domain app generation, environment management, and advanced server orchestration.

The zc CLI tool accelerates your entire development lifecycle — from interactive multi-database bootstrapping and 7-layer domain scaffolding to cryptographically secure secret generation and cascading server orchestration with transparent Uvicorn argument forwarding.

Command Overview

Command	Purpose	Flags / Options
`zc`	Launches the interactive dashboard with auto-detected project context.	—
`zc init [name]`	Scaffolds a full ZCore project with driver selection and `.venv` setup.	`--db [sqlite\|postgres\|mysql]` `-y, --yes` (Use defaults)
`zc startapp [name]`	Generates a 7-layer modular domain module / plugin.	`--template / --no-template` `--test / --no-test` `-y, --yes` (All layers)
`zc run [app]`	Launches the development/production server with cascading config.	`--host <ip>` `--port <port>` `--reload / --no-reload` `--workers <n>` `--log-level <level>` `--env-file <path>` `[extra uvicorn args...]`
`zc gensecret`	Generates a 64-character cryptographically secure `SECRET_KEY`.	—
`zc genenv`	Introspects the `Settings` class and exports an `.env.example` schema.	`-o, --output` (Default: `.env.example`) `-f, --force` (Overwrite)
`zc --version`	Displays the active ZCore Framework version.	—

1. Interactive Dashboard (`zc`)

Running zc with no arguments opens the interactive terminal dashboard powered by Rich and Questionary. It automatically detects whether you are inside an active ZCore project or managing a multi-project workspace:

zc

⚡ ZCore Framework v0.1.0-rc.2 • Modern Modular Monolith
   FastAPI • SQLAlchemy 2.0 • Pydantic V2

  Context: Active Project (core_api)

? What framework task would you like to perform?
❯ 🧩  startapp   — Scaffold a modular domain app / plugin
  ⚡  run        — Launch Uvicorn development server
  📋  genenv     — Generate template .env from Settings class
  🔑  gensecret  — Generate cryptographically secure SECRET_KEY
  📦  init       — Scaffold another ZCore project
  🚪  exit       — Exit CLI

2. Initializing a New Project (`zc init`)

Create a complete project structure with automated database driver configuration and isolated virtual environment setup:

Interactive Mode:

zc init my_project

You will be prompted to choose:

Primary Database Driver: SQLite (aiosqlite), PostgreSQL (asyncpg), or MySQL (aiomysql).
Virtual Environment & Dependencies: Automatically create .venv and install packages using uv (ultra-fast) or pip.

Non-Interactive (CI/CD or Quick Scripts):

# Scaffold with PostgreSQL driver without prompts
zc init my_project --db postgres -y

Generated Project Tree:

📁 my_project/
├── 📄 main.py            # FastAPI lifespan, kernel setup, and middleware stack
├── 📄 .env               # Pre-configured DATABASE_URL and fresh SECRET_KEY
├── 📄 requirements.txt   # Core framework + selected async database driver
├── 📄 .gitignore         # Comprehensive Python and environment ignore rules
└── 📦 .venv/             # Optional isolated virtual environment

3. Scaffolding Modular Domain Apps (`zc startapp`)

ZCore promotes a Modular Monolith architecture where each business domain is an isolated plugin folder containing up to 7 architectural layers:

Interactive Mode:

zc startapp order_management

You can choose between:

Full Boilerplate: Generates ready-to-use template code for all selected layers.
Clean / Blank: Generates clean, empty files for all selected layers.
Custom / Mixed: Granularly select which layers get boilerplate templates and which stay blank.

Non-Interactive Mode:

# Generate all layers with boilerplate and tests
zc startapp order_management -y

# Scaffold without boilerplate templates
zc startapp order_management --no-template

Generated Domain Module:

📁 order_management/
├── 📄 __init__.py
├── 📄 models.py                 # SQLAlchemy 2.0 mapped model with UUID PK
├── 📄 schemas.py                # Zchema Pydantic V2 schemas (Base, Create, Update, Response)
├── 📄 repositories.py           # BaseRepository subclass with full async CRUD and soft-delete/restore
├── 📄 services.py               # BaseService subclass with pre/post execution hooks
├── 📄 routers.py                # BaseRouter scaffold exposing 8 RESTful & lookup endpoints
├── 📄 plugin.py                 # Modular Plugin lifecycle class for Kernel registration
└── 📄 test_order_management.py  # Pytest async test suite using ZTestClient

4. Running the Server (`zc run`)

Launch the server with cascading configuration resolution (CLI Arguments > .env File > Defaults) and transparent Uvicorn argument forwarding:

Basic Execution (Reads `.env`):

zc run

Advanced Parameter Overrides:

# Custom host, port, and disabled reload
zc run --host 0.0.0.0 --port 8080 --no-reload

# Multi-worker production setup (automatically disables --reload)
zc run --workers 4 --log-level warning

# Custom entrypoint and custom env file
zc run app.api:app --env-file .env.production

Transparent Uvicorn Passthrough:

Any unrecognized flags passed to zc run are forwarded directly to the underlying Uvicorn process:

zc run --proxy-headers --forwarded-allow-ips="*" --timeout-keep-alive 30

Cascading Precedence: zc run checks .env for keys like APP_MODULE, UVICORN_APP, HOST, PORT, RELOAD, WORKERS, and LOG_LEVEL. Explicit CLI arguments take highest priority, followed by .env variables, falling back to safe defaults (127.0.0.1:8000).

5. Managing Secrets and Environment Schemas

Generate a Cryptographic Secret:

zc gensecret

Outputs a secure 64-character hexadecimal key (using secrets.token_hex(32)) ready for your production .env under SECRET_KEY.

Generate `.env.example` from Pydantic Settings:

zc genenv -o .env.example -f

Introspects your registered Settings class (including all custom subclassed fields and defaults) and writes a synchronized .env.example template.

Security Best Practice: Always run zc genenv and commit the generated .env.example to version control. Never commit actual .env files. Keep real secrets in environment variables or your secure production vault.

On this page