Skip to content

This repository documents the standalone codex-django-cli package. It provides project scaffolding and blueprints.

Getting Started

Why not django-admin startproject?

Unlike Django's default utility which creates an entirely empty structure, codex-django assembles a much richer baseline: - Modern Frontend Stack: Comes pre-wired with HTMX 2.x and Alpine.js, modular CSS, and base themes. - Ready-to-use Core/System: Includes pre-configured ASGI, Redis, SEO/admin foundations, reusable project settings support, and an opinionated runtime layout that can later be extended with cabinet, conversations, booking, and service-worker layers. - Interactive Menu: You don't need to memorize long CLI flags. Run codex-django menu to initialize a project, extend an existing scaffold, generate repo config files, or create Docker/CI files from the same menu system.

Install The CLI

Install the CLI globally using uv (recommended):

uv tool install codex-django-cli

Or using classic pip:

pip install codex-django-cli

codex-django-cli requires Python 3.12+.

Scaffold A New Project

The CLI registers the codex-django command. You can use the interactive menu or pass explicit flags for automation:

# 1. Interactive wizard
codex-django menu

# 2. Fast path with explicit flags for power users:
codex-django init myproject --i18n --languages en,ru --with-cabinet --with-booking
cd myproject
# Make sure you are in a dedicated virtual environment
pip install -e .
python src/myproject/manage.py migrate
python src/myproject/manage.py startserver

[!IMPORTANT] The codex-django Dependency: The pip install -e . step is critical! It downloads and installs the core codex-django runtime library. The codex-django-cli only generates the scaffolding (the architectural wiring). The actual runtime that powers HTMX responses, cabinet templates, reusable settings, and SEO support lives inside codex-django. Without it, your scaffolded project will not work.

The interactive menu is also accessible simply by typing codex-django. It is useful when you want to choose i18n modes, set language codes, decide which layers to scaffold, or generate comparison copies for already-detected modules without memorizing flags.

If you already have a scaffolded project, extend it incrementally using the CLI menu:

codex-django menu
# -> Choose "🧩  Extend existing Django project"
# -> Select project target from src/
# -> Choose Cabinet, Conversations, Booking engine, Booking cabinet integration, or compare-copy actions

The scaffolding engine generates files and prints the exact follow-up steps you need to wire them into the repository and runtime project.

Typical Development Loop for the CLI

If you are developing the CLI itself, use standard uv commands:

uv sync --extra dev
uv run python tools/dev/check.py