CLI Usage

Django-CFG provides management commands to generate type-safe API clients from your Django REST Framework API. This guide covers all available commands and common workflows.

Available Commands

`generate_client`

Generate API clients defined in your openapi.groups configuration.


python manage.py generate_client

This command:

Reads groups from your Django-CFG openapi configuration
Generates OpenAPI schemas for each group
Parses schemas to IR (Intermediate Representation)
Creates TypeScript, Python, Go, Swift, and Proto clients for each group
Outputs clients to the configured directory

Options:

Flag	Description
Language Selection
`--typescript`	Generate TypeScript client only
`--python`	Generate Python client only
`--go`	Generate Go client only
`--proto`	Generate Protocol Buffer definitions only
`--swift`	Generate Swift client (uses apple/swift-openapi-generator)
`--swift-codable`	Generate simple Swift Codable types without OpenAPIRuntime dependency
Skip Languages
`--no-typescript`	Skip TypeScript generation
`--no-python`	Skip Python generation
`--no-go`	Skip Go generation
`--no-proto`	Skip Protocol Buffer generation
External Generators
`--external-go`	Use oapi-codegen instead of built-in Go generator
`--external-python`	Use openapi-python-client instead of built-in Python generator
`--check-external`	Check which external generators are installed
Group Selection
`--groups NAME [NAME]`	Generate specific groups (default: all)
Utility
`--dry-run`	Validate without generating files
`--list-groups`	List configured groups and exit
`--validate`	Validate configuration and exit
`--interactive`, `-i`	Run in interactive mode (requires click)
`--streamlit`	Copy Python clients to Streamlit admin
`--verbose`	Show detailed error messages with full tracebacks

Examples:


# Generate all clients for all groups
python manage.py generate_client
 
# Generate TypeScript only
python manage.py generate_client --typescript
 
# Generate for specific groups
python manage.py generate_client --groups core shop
 
# Generate Proto files only for one group
python manage.py generate_client --groups profiles --proto
 
# Generate Swift client (uses apple/swift-openapi-generator)
python manage.py generate_client --swift
 
# Generate simple Swift Codable types (no OpenAPIRuntime dependency)
python manage.py generate_client --swift-codable
 
# Validate configuration without generating
python manage.py generate_client --validate
 
# List all configured groups
python manage.py generate_client --list-groups
 
# Check external generator availability
python manage.py generate_client --check-external
 
# Use external Go generator (oapi-codegen)
python manage.py generate_client --external-go

`validate_openapi`

Validate DRF serializers and OpenAPI schemas before generation.


python manage.py validate_openapi

This command analyzes your serializers for common issues that affect code generation quality.

Options:

Flag	Description
Scope
`--app APP`	Validate specific Django app
`--file FILE`	Validate specific file
`--pattern PATTERN`	File pattern to match (default: `*serializers.py`)
Actions
`--fix`	Auto-fix issues where possible
`--dry-run`	Show what would be fixed without changing files
`--no-confirm`	Don’t ask for confirmation before fixing
Reporting
`--report {console,json,html}`	Output format (default: console)
`--output FILE`	Write report to file
`--summary`	Show summary only (compact output)
Filtering
`--severity {error,warning,info}`	Minimum severity to show
`--rule RULE_ID`	Show only specific rule
`--fixable-only`	Show only auto-fixable issues
Info
`--list-rules`	List all available validation rules
`--verbose`	Show detailed output

Examples:


# Validate all serializers
python manage.py validate_openapi
 
# Validate specific app
python manage.py validate_openapi --app accounts
 
# Auto-fix issues
python manage.py validate_openapi --fix
 
# Generate HTML report
python manage.py validate_openapi --report html --output report.html
 
# List available rules
python manage.py validate_openapi --list-rules
 
# Show only errors
python manage.py validate_openapi --severity error

Validation Rules:

Rule ID	Description
`type-hint-missing`	Field missing type hint
`type-hint-any`	Field uses `Any` type
`dict-field-no-model`	DictField without `nested_model_class`
`dict-field-json`	DictField should use JSONField

Quick Start

Generate All Clients from Groups

The simplest approach - generate all clients defined in your configuration:


python manage.py generate_client

This uses your openapi.groups configuration:


# api/config.py
openapi: OpenAPIConfig = OpenAPIConfig(
    enabled=True,
    groups=[
        OpenAPIGroupConfig(name="core", apps=["users", "accounts", "api_keys"], title="Core API"),
        OpenAPIGroupConfig(name="trading", apps=["wallets", "orders", "transactions"], title="Trading API"),
    ],
)

Generate Single Language

For more control, generate specific languages:


# TypeScript only
python manage.py generate_client --typescript
 
# Python only
python manage.py generate_client --python
 
# Go only
python manage.py generate_client --go
 
# Proto only
python manage.py generate_client --proto
 
# Swift only (external generator)
python manage.py generate_client --swift

Generate for Specific Groups


# Generate only core group
python manage.py generate_client --groups core
 
# Generate core and trading groups
python manage.py generate_client --groups core trading

Common Workflows

Development Workflow

During active development, regenerate clients frequently:


# Quick regeneration (all languages, all groups)
python manage.py generate_client
 
# Validate before generating
python manage.py generate_client --validate

Frontend-Only Workflow

If you only need TypeScript clients:


# Generate TypeScript only, skip others
python manage.py generate_client --typescript

Generation options (fetchers, hooks, zod schemas) are configured in OpenAPIConfig:


openapi: OpenAPIConfig = OpenAPIConfig(
    enabled=True,
    generate_zod_schemas=True,   # Runtime validation
    generate_fetchers=True,       # Typed fetch functions
    generate_swr_hooks=True,      # React SWR hooks
    generate_package_files=True,  # package.json, tsconfig.json
    groups=[...],
)

Backend-Only Workflow

For Python microservices needing to call your API:


# Generate Python only
python manage.py generate_client --python

Mobile (Swift) Workflow

For iOS apps using Swift:


# Generate Swift clients (uses apple/swift-openapi-generator)
python manage.py generate_client --swift
 
# Generate simple Swift Codable types (no OpenAPIRuntime dependency)
python manage.py generate_client --swift-codable
 
# Or generate proto for Swift gRPC
python manage.py generate_client --proto

Swift Generators

There are two Swift generation modes:

--swift uses Apple’s official swift-openapi-generator and requires the OpenAPIRuntime dependency. Install with: brew install swift-openapi-generator
--swift-codable generates simple Swift Codable structs with no external dependencies. Ideal for lightweight projects or when you want full control over networking.

Multi-Group Workflow

Generate separate clients for different API groups:


# Generate all languages for specific groups
python manage.py generate_client --groups core shop
 
# Generate TypeScript only for core group
python manage.py generate_client --groups core --typescript
 
# List available groups
python manage.py generate_client --list-groups

Output Examples

Successful Generation


$ python manage.py generate_client
 
🧹 Cleaning schemas: openapi/schemas
🧹 Cleaning clients: openapi/clients
 
Generating clients for 3 group(s):
 
  • core (Core API)
  • trading (Trading API)
  • market (Market API)
 
Languages:
  → Python (built-in)
  → TypeScript (built-in)
  → Go (built-in)
  → Protocol Buffers (built-in)
 
============================================================
 
📦 Processing group: core
  Apps: users, accounts, api_keys
  → Generating OpenAPI schema...
  ✅ Schema saved: openapi/schemas/core.yaml
  → Parsing to IR...
  ✅ Parsed: 15 schemas, 32 operations
  ✅ Python: openapi/clients/python/core (12 files)
  ✅ TypeScript: openapi/clients/typescript/core (28 files)
  ✅ Go: openapi/clients/go/core (8 files)
  ✅ Proto: openapi/clients/proto/core (6 files)
  → Archiving...
  ✅ Archived
 
📦 Processing group: trading
  ...
 
============================================================
 
✅ Successfully generated clients for 3 group(s)!
 
Output directory: openapi/
  Python:     openapi/clients/python/
  TypeScript: openapi/clients/typescript/
  Go:         openapi/clients/go/

Validation Output


$ python manage.py validate_openapi
 
🔍 Validating OpenAPI schemas...
 
Checking app: accounts
  ✅ UserSerializer - OK
  ⚠️  ProfileSerializer - 2 issues
    → type-hint-missing: Field 'metadata' missing type hint (line 45)
    → dict-field-no-model: DictField 'settings' without nested_model_class (line 52)
 
Checking app: payments
  ✅ PaymentSerializer - OK
  ✅ TransactionSerializer - OK
 
============================================================
 
Summary:
  ✅ Passed: 3 serializers
  ⚠️ Warnings: 1 serializer (2 issues)
  ❌ Errors: 0 serializers
 
Run with --fix to auto-fix 1 issue(s)

Compiling Proto Files

After generation, compile proto files for your target language:

Python (grpcio-tools)


# Install dependencies
pip install grpcio grpcio-tools
 
# Compile proto files
cd openapi/clients/proto/profiles
python -m grpc_tools.protoc -I. \
  --python_out=. \
  --grpc_python_out=. \
  api__profiles/*.proto

Go


# Install dependencies
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
 
# Compile proto files
cd openapi/clients/proto/profiles
protoc -I. \
  --go_out=. \
  --go-grpc_out=. \
  api__profiles/*.proto

TypeScript (ts-proto)


# Install dependencies
npm install ts-proto
 
# Compile proto files
cd openapi/clients/proto/profiles
protoc -I. \
  --plugin=./node_modules/.bin/protoc-gen-ts_proto \
  --ts_proto_out=. \
  api__profiles/*.proto

Swift


# Install dependencies
brew install protobuf swift-protobuf grpc-swift
 
# Compile proto files
cd openapi/clients/proto/profiles
protoc -I. \
  --swift_out=. \
  --swift_opt=Visibility=Public \
  api__profiles/*.proto

Auto-Generated README

Each generated proto group includes a README.md with detailed compilation commands for all supported languages.

Troubleshooting

No Operations Found

If generation succeeds but creates empty clients:

1. Check ViewSets are registered:


# users/api/views.py
from rest_framework import viewsets
 
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

2. Verify URL patterns:


# users/urls.py
from rest_framework.routers import DefaultRouter
 
router = DefaultRouter()
router.register('users', UserViewSet)
urlpatterns = router.urls

3. Validate OpenAPI schema:


python manage.py generate_client --validate

TypeScript Compilation Errors

If generated TypeScript has errors:

1. Install dependencies:


cd frontend
npm install zod swr

2. Check TypeScript configuration:


{
  "compilerOptions": {
    "strict": true,
    "skipLibCheck": true,
    "esModuleInterop": true
  }
}

3. Run validation before generation:


python manage.py validate_openapi
python manage.py generate_client

Python Import Errors

If Python client can’t be imported:

1. Ensure output directory is in Python path:


import sys
sys.path.append('/path/to/backend')
 
from api_client import APIClient

2. Install dependencies:


pip install pydantic>=2.0 httpx>=0.24

3. Verify init.py files exist:


ls -la backend/api_client/__init__.py

Schema Generation Fails

Common issues with drf-spectacular:

1. Install drf-spectacular:


pip install drf-spectacular>=0.26.5

2. Configure Django settings:


INSTALLED_APPS = [
    # ...
    'rest_framework',
    'drf_spectacular',
]
 
REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

3. Check for validation errors:


python manage.py validate_openapi --verbose

External Generator Not Found

If Swift or external generators fail:

1. Check installation:


python manage.py generate_client --check-external

2. Install missing generators:


# Swift
brew install swift-openapi-generator
 
# Go (oapi-codegen)
go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest
 
# Python (openapi-python-client)
pip install openapi-python-client

Advanced Usage

Custom Output Directories

Configure output directory in OpenAPIConfig:


openapi: OpenAPIConfig = OpenAPIConfig(
    enabled=True,
    output_dir="openapi",  # Base output directory
    groups=[...],
)

This creates:

openapi/schemas/ - OpenAPI schema files
openapi/clients/python/ - Python clients
openapi/clients/typescript/ - TypeScript clients
openapi/clients/go/ - Go clients
openapi/clients/proto/ - Protocol Buffer files
openapi/clients/swift/ - Swift clients (when —swift used)
openapi/archive/ - Archived versions (when enabled)

Archive System

Django-CFG maintains version history of generated clients:


openapi: OpenAPIConfig = OpenAPIConfig(
    enable_archive=True,           # Enable archiving
    archive_retention_days=30,     # Keep for 30 days
    groups=[...],
)

Archives are stored in openapi/archive/YYYYMMDD_HHMMSS/.

CI/CD Integration

Example GitHub Actions workflow:


name: Generate API Clients
 
on:
  push:
    paths:
      - 'api/**'
      - 'config/**'
 
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: Validate schemas
        run: |
          python manage.py validate_openapi
 
      - name: Generate API clients
        run: |
          python manage.py generate_client
 
      - name: Commit generated clients
        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 Integration

Generate clients in Docker:


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

Pre-commit Hook

Auto-generate clients on commit:


# .git/hooks/pre-commit
#!/bin/bash
python manage.py validate_openapi || exit 1
python manage.py generate_client
git add openapi/

Best Practices

1. Version Control Generated Code

Always commit generated clients:


git add openapi/
git commit -m "Update API clients"

2. Validate Before Generating

Run validation to catch issues early:


python manage.py validate_openapi
python manage.py generate_client

3. Use Groups for Organization

Configure logical groups in Django-CFG:


groups=[
    OpenAPIGroupConfig(name="core", apps=["users", "accounts", "api_keys"], title="Core API"),
    OpenAPIGroupConfig(name="trading", apps=["wallets", "orders", "transactions"], title="Trading API"),
]

4. Enable All Type Safety Features

Configure all features in OpenAPIConfig:


openapi: OpenAPIConfig = OpenAPIConfig(
    enabled=True,
    generate_zod_schemas=True,        # Runtime validation
    generate_package_files=True,      # Proper TypeScript setup
    generate_fetchers=True,           # Universal fetch functions
    generate_swr_hooks=True,          # React integration
    groups=[...],
)

5. Use Verbose Mode for Debugging

When issues occur, use verbose mode:


python manage.py generate_client --verbose

Next Steps

Group Configuration - Configure API groups
Generated Clients - Use generated clients

Pro Tip

Add validation and generation to your deployment script:


python manage.py validate_openapi
python manage.py generate_client