Skip to Content
DocumentationCLI ToolsCommand ReferenceCore Commands

Core Management Commands

Essential commands for Django-CFG project setup, configuration management, and validation.

Project Setup

django-cfg create-project

Creates a new Django project with complete Django-CFG setup.

django-cfg create-project PROJECT_NAME [OPTIONS]

Arguments:

  • PROJECT_NAME - Name of the new Django project

Options:

  • --path, -p PATH - Directory where to create the project (default: current directory)
  • --no-deps - Skip automatic dependency installation
  • --use-pip - Use pip instead of Poetry for dependency installation
  • --force - Overwrite existing directory if it exists
  • --no-setup - Skip automatic project setup (directories, migrations)
  • --no-sample-data - Skip sample data population (users, posts, products)

Examples:

# Basic project creation
django-cfg create-project "My Awesome Project"
 
# Create in specific directory
django-cfg create-project "E-Commerce Site" --path ./projects/
 
# Skip dependency installation
django-cfg create-project "Quick Test" --no-deps
 
# Use pip instead of Poetry
django-cfg create-project "Legacy Project" --use-pip
 
# Minimal setup without sample data
django-cfg create-project "Production App" --no-sample-data
 
# Force overwrite existing directory
django-cfg create-project "My Project" --force
 
# Complete manual setup
django-cfg create-project "Custom Setup" --no-deps --no-setup

What it creates:

  • ✅ Complete Django project structure
  • ✅ Type-safe configuration with Pydantic v2
  • ✅ Multi-database setup with routing
  • ✅ Modern Unfold admin interface
  • ✅ API documentation with Spectacular
  • ✅ JWT authentication system
  • ✅ Background task processing
  • ✅ Docker deployment files
  • ✅ Sample applications (blog, shop, profiles)
  • ✅ 10 test users, 20 blog posts, 30 products (if not skipped)

django-cfg info

Shows Django-CFG installation and system information.

django-cfg info [OPTIONS]

Options:

  • --verbose, -v - Show detailed information including paths

Examples:

# Basic information
django-cfg info
 
# Detailed information with paths
django-cfg info --verbose

Output includes:

  • Django-CFG version and Python version
  • 📋 Project template availability and status
  • Core dependencies (Django, Pydantic, Click)
  • 🌐 Service integrations (Twilio, SendGrid, OpenAI)
  • Admin & UI packages (Unfold, Constance)
  • 📊 API & documentation tools (DRF, Spectacular)
  • Background processing (Django-RQ, Redis)
  • Development tools (Ngrok)

Configuration Management

validate_config

Validates Django-CFG configuration files and settings.

python manage.py validate_config [OPTIONS]

Options:

  • --show-details - Show detailed validation results
  • --check-connections - Test database and service connections
  • --format [json|yaml|table] - Output format (default: table)

Examples:

# Basic validation
python manage.py validate_config
 
# Detailed validation with connection tests
python manage.py validate_config --show-details --check-connections
 
# JSON output for automation
python manage.py validate_config --format json

Validates:

  • ✅ Pydantic model validation
  • ✅ Database connection strings
  • ✅ Service API keys and credentials
  • ✅ File paths and permissions
  • ✅ Environment variable resolution

show_config

Displays current Django-CFG configuration.

python manage.py show_config [OPTIONS]

Options:

  • --format [json|yaml|table] - Output format (default: yaml)
  • --include-secrets - Include sensitive values (use with caution)
  • --section TEXT - Show specific configuration section

Examples:

# Show all configuration
python manage.py show_config
 
# JSON format for automation
python manage.py show_config --format json
 
# Show only database configuration
python manage.py show_config --section database
 
# Include sensitive values (be careful!)
python manage.py show_config --include-secrets

check_settings

Comprehensive validation and debugging for Django-CFG configuration.

python manage.py check_settings [OPTIONS]

Options:

  • --email-test - Test email configuration
  • --verbose - Verbose output with detailed diagnostics

Examples:

# Check all settings
python manage.py check_settings
 
# Test email configuration
python manage.py check_settings --email-test
 
# Verbose output with detailed diagnostics
python manage.py check_settings --verbose

Checks:

  • Configuration validity
  • Database connections
  • Email settings
  • Service integrations
  • File permissions
  • Environment variables

API Endpoints Testing

check_endpoints

Check health and availability of all registered API endpoints.

python manage.py check_endpoints [OPTIONS]

Options:

  • --include-unnamed - Include unnamed URL patterns in the check
  • --timeout INTEGER - Request timeout in seconds (default: 5)
  • --json - Output results as JSON
  • --url TEXT - Check specific endpoint by URL name
  • --no-auth - Disable automatic JWT authentication retry (default: enabled)

Examples:

# Check all endpoints (with auto-auth for protected endpoints)
python manage.py check_endpoints
 
# Include unnamed URL patterns
python manage.py check_endpoints --include-unnamed
 
# Custom timeout (10 seconds)
python manage.py check_endpoints --timeout 10
 
# Disable auto-auth (show 401/403 as-is)
python manage.py check_endpoints --no-auth
 
# JSON output for automation/CI
python manage.py check_endpoints --json
 
# Check specific endpoint by name
python manage.py check_endpoints --url endpoints_status

Output:

❌ Overall Status: UNHEALTHY
 
📊 Summary:
  Total endpoints: 399
  ✅ Healthy: 0
  ⚠️  Warnings: 0
  ❌ Unhealthy: 69
  ❌ Errors: 90
  ⏭️  Skipped: 240
 
🔗 Endpoints:
  ✅ endpoints_status
     URL: /cfg/api/endpoints/
     Status: healthy
     Response time: 0.123s
 
  ✅ api_users_list
     URL: /api/users/
     Status: healthy
     Response time: 0.245s
     🔐 Required JWT authentication
 
  ❌ api_payments_list
     URL: /api/payments/
     Status: unhealthy
     Error: Database connection failed

JSON Output:

{
  "status": "unhealthy",
  "timestamp": "2025-10-05T18:00:20.111738+00:00",
  "total_endpoints": 399,
  "healthy": 0,
  "unhealthy": 69,
  "warnings": 0,
  "errors": 90,
  "skipped": 240,
  "endpoints": [
    {
      "url": "/cfg/api/endpoints/",
      "url_name": "endpoints_status",
      "namespace": "",
      "group": "cfg/api/endpoints",
      "view": "EndpointsStatusView",
      "status": "healthy",
      "status_code": 200,
      "response_time_ms": 0.23,
      "is_healthy": true,
      "last_checked": "2025-10-05T18:00:20.111738+00:00",
      "required_auth": false
    },
    {
      "url": "/api/users/",
      "url_name": "api_users_list",
      "namespace": "",
      "group": "api/users",
      "view": "UserViewSet",
      "status": "healthy",
      "status_code": 200,
      "response_time_ms": 0.45,
      "is_healthy": true,
      "last_checked": "2025-10-05T18:00:20.211738+00:00",
      "required_auth": true
    }
  ]
}

What it checks:

  • ✅ All registered URL patterns
  • ✅ HTTP status codes (200, 401, 403, etc.)
  • ✅ Response times in milliseconds
  • ✅ Endpoint availability
  • ✅ Error detection and reporting
  • ✅ Grouping by URL namespace

Excluded endpoints:

  • ❌ Admin endpoints (/admin/)
  • ❌ Static/media files (/static/, /media/)
  • ❌ Health check endpoints (/cfg/health/)
  • ❌ Schema documentation (/schema/)
  • ❌ Django debug toolbar (/__debug__/, /__reload__/)

Status Categories:

StatusDescriptionHTTP Codes
HealthyEndpoint working correctly200-299, 301-308, 401, 403, 405
WarningMight be OK (no data)404
UnhealthyEndpoint has issues400, 500+
ErrorException occurredConnection errors, timeouts
SkippedRequires parametersURLs with <pk>, <id>

Use Cases:

Development:

# Quick check during development
python manage.py check_endpoints

CI/CD Pipeline:

# Automated testing in GitHub Actions
python manage.py check_endpoints --json > endpoints-report.json

Production Monitoring:

# Health check with custom timeout
python manage.py check_endpoints --timeout 10

Debugging:

# Check specific problematic endpoint
python manage.py check_endpoints --url api_users_list

Features:

  • ✅ Auto-discovers all registered endpoints
  • ✅ Smart JWT Auto-Authentication - Automatically retries protected endpoints with JWT token
  • ✅ Creates test user endpoint_test_user once and reuses token
  • ✅ Respects Django Test Client
  • ✅ No ALLOWED_HOSTS issues (uses localhost)
  • ✅ Excludes schema documentation (prevents rate limiting issues)
  • ✅ Excludes recursive endpoints (health checks)
  • ✅ Colored console output with emojis
  • ✅ JSON export for automation
  • ✅ Response time measurement
  • ✅ Indicates which endpoints required authentication (🔐)

Database Operations

migrate_all

Migrate all databases based on django-cfg configuration.

python manage.py migrate_all [OPTIONS]

Options:

  • --dry-run - Show what would be migrated without executing
  • --skip-makemigrations - Skip makemigrations step

Examples:

# Migrate all databases
python manage.py migrate_all
 
# Dry run to see what would happen
python manage.py migrate_all --dry-run
 
# Skip makemigrations
python manage.py migrate_all --skip-makemigrations

Features:

  • Auto-detects all databases from django-cfg configuration
  • Creates migrations for all apps
  • Migrates each database based on routing configuration
  • Migrates constance separately
  • Handles app-specific routing

migrator

Interactive database migration tool with automatic database detection and routing support.

python manage.py migrator [OPTIONS]

Options:

  • --auto - Automatic migration mode (no prompts, migrates all databases)
  • --database TEXT - Target specific database only
  • --app TEXT - Target specific app only

Examples:

# Interactive mode (default) - shows menu
python manage.py migrator
 
# Auto-migrate all databases (no prompts)
python manage.py migrator --auto
 
# Migrate specific database
python manage.py migrator --database blog_db
 
# Migrate specific app across all databases
python manage.py migrator --app blog
 
# Migrate specific app on specific database
python manage.py migrator --database blog_db --app blog

Interactive Mode:

When run without --auto, shows an interactive menu:

🗄️  Django Database Migrator
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Current Configuration:
   Databases: default, blog_db, shop_db
   Apps: accounts, blog, shop, profiles

What would you like to do?
> Migrate all databases (recommended)
  Migrate specific database
  Show database status
  View configuration info
  Exit

Auto Mode (--auto):

Runs automatic migration without prompts:

  1. Creates migrations - Runs makemigrations for all apps
  2. Migrates default database - Migrates main database first
  3. Migrates routed databases - Migrates blog_db, shop_db based on routing rules
  4. Migrates constance - Always migrates constance app (required by django-cfg)

Example Output:

$ python manage.py migrator --auto
 
🚀 Running automatic migration...
 
📦 Creating migrations for all apps...
✅ Migrations created successfully
 
🔄 Migrating database: default
  📦 Migrating all apps...
  ✅ Migrations completed for default
 
🔄 Migrating database: blog_db
  📦 Migrating app: blog
  ✅ Migrations completed for blog_db
 
🔄 Migrating database: shop_db
  📦 Migrating app: shop
  ✅ Migrations completed for shop_db
 
✅ Constance migrated successfully

How Routing Works:

The migrator respects DATABASE_ROUTING_RULES from settings:

DATABASE_ROUTING_RULES = {
    'blog': 'blog_db',
    'shop': 'shop_db',
}
  • Apps listed in routing rules → migrate on their target database only
  • Apps NOT listed → migrate on default database
  • Constance app → always migrates on default database

Comparison with migrate_all:

Featuremigrator --automigrate_all
Interactive menu✅ Yes (without —auto)❌ No
Auto makemigrations✅ Yes✅ Yes (unless —skip-makemigrations)
Respects routing rules✅ Yes✅ Yes
Specific database✅ —database flag❌ Migrates all
Specific app✅ —app flag❌ Migrates all apps
Constance handling✅ Automatic✅ Automatic
Best forDevelopment, targeted migrationsProduction, CI/CD

Use Cases:

Development:

# Quick migration during development
python manage.py migrator --auto

Testing specific database:

# Test blog database migrations only
python manage.py migrator --database blog_db

Troubleshooting:

# Interactive mode to explore database status
python manage.py migrator
# Select "Show database status" from menu

CI/CD Pipeline:

# Production deployment - use migrate_all
python manage.py migrate_all

Features:

  • ✅ Automatic database discovery from settings
  • ✅ Respects DATABASE_ROUTING_RULES
  • ✅ Interactive menu with questionary
  • ✅ Progress indicators with emojis
  • ✅ Database status checking
  • ✅ Configuration info display
  • ✅ Constance app auto-migration

Development Server

runserver (Enhanced)

Enhanced development server with better output and options.

poetry run cli runserver [OPTIONS]

Options:

  • --port INTEGER - Port number (default: 8000)
  • --host TEXT - Host address (default: 127.0.0.1)
  • --debug - Enable debug mode
  • --no-reload - Disable auto-reload

Examples:

# Basic server
poetry run cli runserver
 
# Custom port and host
poetry run cli runserver --port 3000 --host 0.0.0.0
 
# Production-like settings
poetry run cli runserver --no-reload --port 8080

Features:

  • Rich colored output
  • 📊 Better error formatting
  • Faster startup time
  • Smart configuration detection

User Management

superuser (Enhanced)

Enhanced superuser creation with better UX.

poetry run cli superuser [OPTIONS]

Options:

  • --email TEXT - Email address for superuser
  • --username TEXT - Username (optional, defaults to email)
  • --interactive - Interactive mode (default)
  • --no-input - Non-interactive mode

Examples:

# Interactive superuser creation
poetry run cli superuser
 
# Pre-fill email
poetry run cli superuser --email [email protected]
 
# Non-interactive (password will be prompted)
poetry run cli superuser --email [email protected] --no-input

create_token

Create API tokens for authentication.

python manage.py create_token USERNAME [OPTIONS]

Arguments:

  • USERNAME - Username to create token for

Options:

  • --name TEXT - Token name/description
  • --expires-in INTEGER - Expiration in days

Examples:

# Create token for user
python manage.py create_token admin
 
# Create token with specific name
python manage.py create_token admin --name "API Access Token"
 
# Create token with expiration (30 days)
python manage.py create_token admin --expires-in 30

URL Management

show_urls (Enhanced)

Lists all URL patterns in the project.

poetry run cli show-urls [OPTIONS]

Options:

  • --format [table|json|list] - Output format (default: table)
  • --include-admin - Include admin URLs
  • --pattern TEXT - Filter URLs by pattern

Examples:

# Show all URLs in table format
poetry run cli show-urls
 
# JSON format for automation
poetry run cli show-urls --format json
 
# Filter API URLs only
poetry run cli show-urls --pattern "api/"
 
# Include admin URLs
poetry run cli show-urls --include-admin

list_urls

List all URL patterns in the project.

python manage.py list_urls [OPTIONS]

Options:

  • --pattern TEXT - Filter by pattern
  • --names-only - Show URL names only
  • --output FILE - Export to file

Examples:

# List all URLs
python manage.py list_urls
 
# Filter by pattern
python manage.py list_urls --pattern api
 
# Show URL names only
python manage.py list_urls --names-only
 
# Export to file
python manage.py list_urls --output urls.txt

Utility Commands

clear_constance

Clear Constance dynamic settings cache.

python manage.py clear_constance [OPTIONS]

Options:

  • --keys TEXT - Clear specific keys (comma-separated)
  • --dry-run - Dry run to see what would be cleared

Examples:

# Clear all constance cache
python manage.py clear_constance
 
# Clear specific keys
python manage.py clear_constance --keys KEY1,KEY2
 
# Dry run to see what would be cleared
python manage.py clear_constance --dry-run

Best Practices

1. Always Validate Before Deploy

# Validate configuration before deployment
python manage.py validate_config --check-connections

2. Use Dry Run for Migrations

# Check what migrations would run
python manage.py migrate_all --dry-run

3. Check Settings After Configuration Changes

# Verify settings after changes
python manage.py check_settings --verbose

4. Create Tokens with Expiration

# Create tokens with limited lifetime
python manage.py create_token user --expires-in 90

5. Export Configuration for Documentation

# Export configuration as YAML
python manage.py show_config --format yaml > docs/config.yaml

Command Workflow Examples

Complete Project Setup

# Create project and initialize
django-cfg create-project "My Project" && \
cd my_project && \
python manage.py validate_config && \
python manage.py migrate_all && \
python manage.py createsuperuser

Pre-Deployment Checklist

# Validate everything before deploying
python manage.py validate_config --check-connections && \
python manage.py check_settings --verbose && \
python manage.py migrate_all --dry-run && \
python manage.py collectstatic --noinput --dry-run

Development Startup

# Quick development environment startup
python manage.py migrate_all && \
python manage.py runserver

Core commands power your Django-CFG project! 🚀

Quick ReferenceDevelopment