Skip to Content
DocumentationFeaturesAuto-Configuring ModulesDjango ClientCLI Commands

CLI Commands Reference

The django_client module provides powerful management commands for generating API clients and validating OpenAPI schema quality.

Commands Overview

CommandPurposeKey Features
generate_clientGenerate TypeScript and Python clientsMulti-group generation, dry-run, interactive mode
validate_openapiValidate and fix OpenAPI schema qualityAuto-fix issues, detailed reports, rule-based validation

generate_client

Generate type-safe TypeScript and Python API clients from your Django REST Framework API.

Basic Usage

# Generate all configured groups
python manage.py generate_client
 
# Generate specific groups
python manage.py generate_client --groups core billing
 
# Generate Python only
python manage.py generate_client --python
 
# Generate TypeScript only
python manage.py generate_client --typescript

Command Options

Generation Options

--groups [GROUP ...]

  • Generate specific groups only
  • Default: all configured groups
python manage.py generate_client --groups core custom

--python

  • Generate Python client only (skip TypeScript)
python manage.py generate_client --python

--typescript

  • Generate TypeScript client only (skip Python)
python manage.py generate_client --typescript

--no-python

  • Skip Python client generation
python manage.py generate_client --no-python

--no-typescript

  • Skip TypeScript client generation
python manage.py generate_client --no-typescript

Utility Options

--dry-run

  • Validate configuration without generating files
  • Shows what will be generated
python manage.py generate_client --dry-run

--list-groups

  • List all configured groups and exit
  • Shows group details and matched apps
python manage.py generate_client --list-groups

--validate

  • Validate configuration and show statistics
python manage.py generate_client --validate

--interactive / -i

  • Run in interactive mode with prompts
  • Requires click package
python manage.py generate_client --interactive

Examples

Basic Generation

Generate all configured groups:

python manage.py generate_client

Output:

Generating clients for 2 group(s):

  • core (Core API)
  • billing (Billing API)

Languages:
  → Python
  → TypeScript

============================================================

📦 Processing group: core
  Apps: users, accounts, profiles
  → Generating OpenAPI schema...
  ✅ Schema saved: openapi/schemas/core.json
  → Parsing to IR...
  ✅ Parsed: 15 schemas, 42 operations
  → Generating Python client...
  ✅ Python client: openapi/clients/python/core (38 files)
  → Generating TypeScript client...
  ✅ TypeScript client: openapi/clients/typescript/core (52 files)
  → Archiving...
  ✅ Archived: openapi/archive/core_2025-01-15_14-30-00.zip

📦 Processing group: billing
  Apps: payments, subscriptions
  → Generating OpenAPI schema...
  ✅ Schema saved: openapi/schemas/billing.json
  → Parsing to IR...
  ✅ Parsed: 8 schemas, 24 operations
  → Generating Python client...
  ✅ Python client: openapi/clients/python/billing (22 files)
  → Generating TypeScript client...
  ✅ TypeScript client: openapi/clients/typescript/billing (31 files)
  → Archiving...
  ✅ Archived: openapi/archive/billing_2025-01-15_14-30-15.zip

============================================================

✅ Successfully generated clients for 2 group(s)!

Output directory: /path/to/project/openapi
  Python:     openapi/clients/python
  TypeScript: openapi/clients/typescript

Specific Groups

Generate only specific groups:

python manage.py generate_client --groups core custom

This is useful when you only changed specific apps, want faster generation during development, or need to regenerate a failed group.

Python Only

Generate Python clients only:

python manage.py generate_client --python

Perfect for backend microservices, Python-to-Python API communication, and testing Python client in isolation.

TypeScript Only

Generate TypeScript clients only:

python manage.py generate_client --typescript

Perfect for frontend development, React/Next.js projects, and React Native apps.

Dry Run

Preview what will be generated:

python manage.py generate_client --dry-run

Output:

🔍 DRY RUN MODE - No files will be generated

Generating clients for 2 group(s):

  • core (Core API)
  • billing (Billing API)

Languages:
  → Python
  → TypeScript

✅ Dry run completed - no files generated

Useful for verifying group configuration, checking which apps are matched, and CI/CD validation.

List Groups

Show all configured groups:

python manage.py generate_client --list-groups

Output:

Configured groups (3):

  • core
    Title: Core API
    Apps: 2 pattern(s)
    Matched: 5 app(s)
      - users
      - accounts
      - profiles
      - auth
      - sessions

  • billing
    Title: Billing API
    Apps: 2 pattern(s)
    Matched: 3 app(s)
      - payments
      - subscriptions
      - invoices

  • content
    Title: Content API
    Apps: 1 pattern(s)
    Matched: 0 apps

Validate Config

Validate configuration and show statistics:

python manage.py generate_client --validate

Output:

Validating configuration...
✅ Configuration is valid!

Statistics:
  • Total groups: 3
  • Total apps in groups: 8
  • Ungrouped apps: 4

Warning: 4 apps not in any group:
  - admin
  - contenttypes
  - sessions
  - messages

Workflow Integration

Pre-Deployment Script

#!/bin/bash
# scripts/generate_clients.sh
 
set -e
 
echo "🚀 Generating API clients..."
python manage.py generate_client
 
echo "✅ Validating TypeScript..."
cd frontend && pnpm tsc --noEmit
 
echo "✅ Validating Python..."
cd ../backend && mypy api_client/
 
echo "🎉 Clients generated and validated!"

GitHub Actions

name: Generate API Clients
 
on:
  push:
    paths:
      - 'api/**'
      - '**/serializers.py'
      - '**/views.py'
 
jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.12'
 
      - name: Install dependencies
        run: pip install -r requirements.txt
 
      - name: Generate clients
        run: python manage.py generate_client
 
      - name: Commit changes
        run: |
          git config --local user.email "[email protected]"
          git config --local user.name "GitHub Action"
          git add openapi/
          git commit -m "chore: update API clients [skip ci]" || true
          git push

Docker Build

FROM python:3.12
 
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
 
COPY . .
 
# Generate clients during build
RUN python manage.py generate_client
 
CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]

validate_openapi

Validate and auto-fix OpenAPI schema quality issues in Django REST Framework serializers.

Why Validation Matters

Poor OpenAPI schema quality causes:

  • ❌ Missing type hints → Any types in generated clients
  • ❌ Missing help text → No documentation in generated code
  • ❌ Ambiguous field types → Runtime errors
  • ❌ Missing read_only → Write attempts on read-only fields

The validator finds and fixes these issues automatically.

Basic Usage

# Check all serializers
python manage.py validate_openapi
 
# Check specific app
python manage.py validate_openapi --app users
 
# Auto-fix issues
python manage.py validate_openapi --fix
 
# Preview fixes without applying
python manage.py validate_openapi --fix --dry-run
 
# Generate HTML report
python manage.py validate_openapi --report html

Command Options

Scope Options

--app APP_NAME

  • Check specific Django app only
python manage.py validate_openapi --app accounts

--file PATH

  • Check specific file only
python manage.py validate_openapi --file users/serializers.py

--pattern PATTERN

  • File pattern to match (default: *serializers.py)
python manage.py validate_openapi --pattern "*api.py"

Action Options

--fix

  • Apply auto-fixes to issues
python manage.py validate_openapi --fix

--dry-run

  • Preview fixes without applying changes
python manage.py validate_openapi --fix --dry-run

--no-confirm

  • Skip confirmation prompts when fixing
python manage.py validate_openapi --fix --no-confirm

Reporting Options

--report {console,json,html}

  • Report format (default: console)
python manage.py validate_openapi --report html

--output PATH

  • Output file for JSON/HTML reports
python manage.py validate_openapi --report html --output report.html

--summary

  • Show summary only (compact output)
python manage.py validate_openapi --summary

Filtering Options

--severity {error,warning,info}

  • Filter by minimum severity level
python manage.py validate_openapi --severity error

--rule RULE_ID

  • Check specific rule only
python manage.py validate_openapi --rule type-hint-001

--fixable-only

  • Show only auto-fixable issues
python manage.py validate_openapi --fixable-only

Utility Options

--list-rules

  • List all validation rules and exit
python manage.py validate_openapi --list-rules

--verbose

  • Show detailed output
python manage.py validate_openapi --verbose

Validation Rules

Common validation rules include:

Rule IDNameSeverityAuto-Fixable
type-hint-001Missing type hintsErrorYes
help-text-001Missing help_textWarningNo
read-only-001Missing read_onlyWarningYes
default-001Missing default valuesInfoNo
max-length-001Missing max_lengthWarningYes

View all rules:

python manage.py validate_openapi --list-rules

Examples

Basic Check

Check all serializers:

python manage.py validate_openapi

Output:

🔍 Scanning for issues...

Found 12 issues in 5 files:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
users/serializers.py
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Line 15: UserSerializer.email
  ❌ ERROR [type-hint-001] Missing type hint
    → Add type hint: email: str = serializers.EmailField(...)
    ✅ Auto-fixable

  Line 18: UserSerializer.bio
  ⚠️  WARNING [help-text-001] Missing help_text
    → Add: help_text="User biography"

  Line 22: UserSerializer.created_at
  ⚠️  WARNING [read-only-001] Missing read_only=True
    → Add: read_only=True
    ✅ Auto-fixable

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
accounts/serializers.py
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Line 30: AccountSerializer.balance
  ❌ ERROR [type-hint-001] Missing type hint
    → Add type hint: balance: Decimal = serializers.DecimalField(...)
    ✅ Auto-fixable

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Summary:
  • Total issues: 12
  • Errors: 5
  • Warnings: 6
  • Info: 1
  • Auto-fixable: 8

💡 Tip: Run with --fix to auto-fix 8 issue(s)

Auto-Fix

Auto-fix issues:

python manage.py validate_openapi --fix

Output:

🔍 Scanning for issues...

Found 12 issues (8 fixable)

🔧 Applying fixes...

✅ Fixed: users/serializers.py:15 [type-hint-001]
✅ Fixed: users/serializers.py:22 [read-only-001]
✅ Fixed: accounts/serializers.py:30 [type-hint-001]
✅ Fixed: payments/serializers.py:45 [max-length-001]
... (4 more)

✅ Successfully fixed 8 issue(s)!

Remaining issues: 4 (manual fix required)

Dry Run

Preview fixes without applying:

python manage.py validate_openapi --fix --dry-run

Shows what would be fixed without modifying files.

Specific App

Check specific app:

python manage.py validate_openapi --app users

Only scans serializers in the users app.

HTML Report

Generate HTML report:

python manage.py validate_openapi --report html --output validation_report.html

Creates an interactive HTML report with sortable/filterable issue table, statistics and charts, code snippets with syntax highlighting, and fix suggestions.

Errors Only

Show only errors:

python manage.py validate_openapi --severity error

Filters out warnings and info messages.

Summary

Show compact summary:

python manage.py validate_openapi --summary

Output:

Summary:
  • Total files checked: 15
  • Files with issues: 5
  • Total issues: 12
  • Errors: 5 (4 fixable)
  • Warnings: 6 (3 fixable)
  • Info: 1 (1 fixable)

Workflow Integration

Pre-Commit Hook

#!/bin/bash
# .git/hooks/pre-commit
 
echo "🔍 Validating OpenAPI schemas..."
 
# Check only staged files
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep "serializers.py$")
 
if [ -n "$STAGED_FILES" ]; then
    for file in $STAGED_FILES; do
        python manage.py validate_openapi --file "$file" --severity error
        if [ $? -ne 0 ]; then
            echo "❌ Validation failed for $file"
            echo "💡 Run: python manage.py validate_openapi --file $file --fix"
            exit 1
        fi
    done
fi
 
echo "✅ All schemas valid"

CI/CD Pipeline

name: Validate OpenAPI Schemas
 
on:
  pull_request:
    paths:
      - '**/*serializers.py'
 
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.12'
 
      - name: Install dependencies
        run: pip install -r requirements.txt
 
      - name: Validate schemas
        run: |
          python manage.py validate_openapi --severity error
          python manage.py validate_openapi --report html --output report.html
 
      - name: Upload report
        uses: actions/upload-artifact@v3
        with:
          name: validation-report
          path: report.html

Weekly Report

#!/bin/bash
# scripts/weekly_validation.sh
 
# Generate comprehensive report
python manage.py validate_openapi \
  --report html \
  --output "reports/validation_$(date +%Y-%m-%d).html"
 
# Send to team (example with curl)
curl -X POST https://your-webhook.com/reports \
  -F "file=@reports/validation_$(date +%Y-%m-%d).html"

Common Workflows

Development Workflow

During active development:

# 1. Validate configuration
python manage.py generate_client --validate
 
# 2. List groups and check matched apps
python manage.py generate_client --list-groups
 
# 3. Validate OpenAPI quality
python manage.py validate_openapi --app myapp
 
# 4. Fix issues
python manage.py validate_openapi --app myapp --fix
 
# 5. Generate clients
python manage.py generate_client

Pre-Deployment Checklist

Before deploying to production:

# 1. Validate everything
python manage.py validate_openapi --severity error
 
# 2. Generate fresh clients
python manage.py generate_client
 
# 3. Run type checks
cd frontend && pnpm tsc --noEmit
cd ../backend && mypy api_client/
 
# 4. Commit changes
git add openapi/
git commit -m "chore: update API clients"

Debugging Issues

When generation fails:

# 1. Check configuration
python manage.py generate_client --validate
 
# 2. List groups
python manage.py generate_client --list-groups
 
# 3. Dry run to see what would happen
python manage.py generate_client --dry-run
 
# 4. Validate schemas
python manage.py validate_openapi --verbose
 
# 5. Generate specific group
python manage.py generate_client --groups problematic_group

Troubleshooting

generate_client Issues

“OpenAPI client generation is not enabled”

# Enable in django-cfg configuration
openapi_client: OpenAPIClientConfig = OpenAPIClientConfig(
    enabled=True,  # ← Must be True
    # ...
)

“No groups to generate”

  • Check that groups are configured
  • Run --list-groups to see matched apps
  • Verify app names match installed apps

“No apps matched for group”

  • Check app name patterns in group configuration
  • Run --list-groups to see matched apps
  • Verify apps are in INSTALLED_APPS

validate_openapi Issues

“No issues found” but clients have any types

  • Check that serializers have type hints
  • Run with --verbose flag
  • Verify correct serializer file pattern

“Auto-fix failed”

  • Run with --dry-run to preview changes
  • Check file permissions
  • Review error messages with --verbose

Best Practices

1. Run Validation Before Generation

Always validate schemas before generating clients:

python manage.py validate_openapi --severity error --fix
python manage.py generate_client

2. Use Dry Run for Testing

Test configuration changes with dry-run:

python manage.py generate_client --dry-run

3. Generate Regularly

Regenerate clients after any API changes:

# After modifying serializers
python manage.py generate_client

4. Version Control Clients

Always commit generated clients:

git add openapi/
git commit -m "chore: update API clients"

5. CI/CD Integration

Automate generation in your CI/CD pipeline (see workflow examples above).

Next Steps

Getting StartedAdvanced