### Quick Start Commands

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/dockerised_dev.md

Commands to start the development environment, run database migrations, and start the Django server. Use `./runproj up` to start all containers and enter the Django container, then run `./manage.py migrate` to set up the database. In a separate terminal, use `./rs` to start the Django server, and `./runproj exec` to get a shell in the running container.

```bash
./runproj up          # Start all containers (drops you into Django container)
./manage.py migrate   # Set up database
./rs                  # Start Django server (in separate terminal: ./runproj exec)
```

--------------------------------

### Install and run django-q2

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/guides/bulk_edit_async.md

Commands to install django-q2, migrate its database tables, and start the qcluster worker in a separate process. Requires django-q2 installed and a worker process ready.

```bash
pip install django-q2
python manage.py migrate django_q
python manage.py qcluster   # run this in a separate process
```

--------------------------------

### Start Django Development Server with ./rs

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/dockerised_dev.md

Shortcut for `./manage.py runserver 0:8001` to start the development server.

```bash
./rs  # Shortcut for ./manage.py runserver 0:8001
```

--------------------------------

### Initial setup: copy templates and generate Tailwind safelist

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/mgmt_commands.md

Two-step initial setup: copy all templates for customization and generate Tailwind safelist if using Tailwind.

```bash
# 1. Copy templates for customization
python manage.py pcrud_mktemplate myapp --all

# 2. Generate Tailwind safelist (if using Tailwind)
python manage.py pcrud_extract_tailwind_classes --output ./config/
```

--------------------------------

### Generate a starter template pack with pcrud_starttemplatepack

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/template_packs/authoring-and-publishing.md

Run this management command from a Django project with PowerCRUD installed to create a starter template pack. It copies the complete DaisyUI template tree by default and creates the package structure shown below. Use --source-template-pack bootstrap5 to start from Bootstrap instead.

```bash
python manage.py pcrud_starttemplatepack my_powercrud_pack ../my-powercrud-pack
```

--------------------------------

### Start Development Environment with ./runproj up

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/dockerised_dev.md

Starts the full development stack: Django container, PostgreSQL, Redis, Vite dev server, and pgAdmin. Automatically places you inside the Django container.

```bash
./runproj up
```

--------------------------------

### Manual-static setup: load vendors and pack assets

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/template_packs/selecting-and-configuring.md

For a package-owned manual-static setup, load the runtime config, then your pack's vendor tags, then the pack's assets. Use the powercrud template tags as shown.

```django
{% load static powercrud %}
{% powercrud_runtime_config %}
{# Your pack's required vendor tags go here. #}
{% powercrud_pack_assets %}
```

--------------------------------

### Start Async Task Processor with ./manage.py qcluster

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/dockerised_dev.md

Starts the django-q2 async task processor in a separate terminal after using `./runproj exec`.

```bash
./manage.py qcluster  # Start async task processor for django-q2
```

--------------------------------

### Start development environment and run tests

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/README.md

Use these commands from the project root to build Docker images, start services, enter the Django container, and run the full local test suite including Playwright and Bootstrap coverage.

```bash
./runproj up          # build images, start services, enter the Django container
./runtests           # run the full local suite, including Playwright and focused Bootstrap coverage
```

--------------------------------

### Start Django-Q2 async task processor

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/dockerised_dev.md

Run this command inside the Django container to start the async task processor using Django-Q2. This is required for processing asynchronous tasks in development.

```bash
# In Django container
./manage.py qcluster  # Start async task processor
```

--------------------------------

### Install and run core and Playwright test suites with constraints files

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/testing.md

Use these commands to reproduce the exact CI compatibility environments. The commands install the test dependencies with `uv pip install` using the specified constraints file and run the tests with `pytest`. The `-m` flag selects the test subset: `not playwright` for core tests, `playwright_smoke` for the curated browser smoke subset, and `playwright` for the full browser suite. The Playwright commands also require `npm ci` and `npm run build` to build static assets.

```bash
# Django 5.2 core suite
uv pip install -c requirements/constraints-django52.txt ".[tests-core]"
pytest -m "not playwright"

# Django 6.1 core suite
uv pip install -c requirements/constraints-django61.txt ".[tests-core]"
pytest -m "not playwright"

# Django 5.2 Playwright smoke subset
uv pip install -c requirements/constraints-django52.txt ".[tests-core]" ".[tests-ui]"
npm ci
npm run build
pytest -m playwright_smoke

# Django 6.1 Playwright smoke subset
uv pip install -c requirements/constraints-django61.txt ".[tests-core]" ".[tests-ui]"
npm ci
npm run build
pytest -m playwright_smoke

# Django 6.1 full Playwright suite
uv pip install -c requirements/constraints-django61.txt ".[tests-core]" ".[tests-ui]"
npm ci
npm run build
pytest -m playwright

```

--------------------------------

### Install a PowerCRUD template pack with pip

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/template_packs/authoring-and-publishing.md

Use this command to install a published PowerCRUD template pack from PyPI or an internal index. The package name is an example; replace with the actual distribution name.

```bash
python -m pip install my-powercrud-pack
```

--------------------------------

### Example: configuring filter_null_fields_exclude in a filterset

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/guides/filtering.md

Lists original field names in filter_null_fields_exclude to opt specific generated filters out of null helpers. Use original field names like 'status', not generated companion names like 'status__isnull'. With this config, 'owner' keeps its 'Empty only' dropdown, 'published_date' gains a 'Published date is empty' companion when added, and 'status' gets no built-in null helper.

```python
filterset_fields = ["owner", "published_date", "status"]
default_filterset_fields = ["owner"]
filter_null_fields_exclude = ["status"]
```

--------------------------------

### Create sample data

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/sample_app.md

Runs the custom management command to populate the database with sample data.

```bash
./manage.py create_sample_data
```

--------------------------------

### Set Up Django Application with makemigrations and migrate

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/dockerised_dev.md

Run inside the Django container to create and apply database migrations.

```bash
# You're now inside the Django container
./manage.py makemigrations
./manage.py migrate
```

--------------------------------

### Install PowerCRUD Python packages

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/guides/getting_started.md

Install the required Python packages neapolitan and django-powercrud using pip.

```bash
pip install neapolitan
pip install django-powercrud
```

--------------------------------

### runbootstrap: Run the Bootstrap sample presentation

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/mgmt_commands.md

Starts Django's development server with config.settings_bootstrap. The --port option is required and must be an integer from 1 to 65535. Running without --port exits with an error.

```bash
./manage.py runbootstrap --port 8003
```

```bash
./runproj exec --command "cd src && ./manage.py runbootstrap --port 8003"
```

--------------------------------

### Install Playwright Chromium browser

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/testing.md

Install the Chromium browser for Playwright. This is required when running outside Docker, as the Chromium browser is baked into the Docker image.

```bash
playwright install chromium

```

--------------------------------

### Worked example: cmms_asset dependent on cmms_property_asset_type_override

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/config_options.md

A worked example of field_queryset_dependencies that filters the 'cmms_asset' field based on the 'cmms_property_asset_type_override' field using the 'property_asset_type_override' lookup.

```python
field_queryset_dependencies = {
    "cmms_asset": {
        "depends_on": ["cmms_property_asset_type_override"],
        "filter_by": {
            "property_asset_type_override": "cmms_property_asset_type_override",
        },
    }
}
```

--------------------------------

### Worked example: genres dependent on author

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/config_options.md

A worked example of field_queryset_dependencies that filters the 'genres' field based on the 'author' field using the 'authors' lookup.

```python
field_queryset_dependencies = {
    "genres": {
        "depends_on": ["author"],
        "filter_by": {"authors": "author"},
    }
}
```

--------------------------------

### Create sample data with create_sample_data

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/sample_app.md

Creates default or custom amounts of authors and books. Use --authors and --books to specify counts, and --books-per-author to control the average number of books per author. Generates realistic data with progress feedback.

```bash
./manage.py create_sample_data

# Create 100 authors and 1000 books
./manage.py create_sample_data --authors 100 --books 1000

# Create 500 books with an average of 5 books per author
./manage.py create_sample_data --books 500 --books-per-author 5
```

--------------------------------

### Deprecated get_list_cell_tooltip example

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/hooks.md

Deprecated list form for get_list_cell_tooltip. Use field-specific hooks instead. This example shows the deprecated list_cell_tooltip_fields list and the hook implementation.

```python
list_cell_tooltip_fields = ["status", "has_invoice"]

def get_list_cell_tooltip(self, obj, field_name, *, is_property, request=None):
    if field_name == "status":
        return obj.status_explanation
    if field_name == "has_invoice":
        return "Invoice attached" if obj.has_invoice else "Invoice missing"
    return None
```

--------------------------------

### Run Bootstrap presentation through project wrapper with runproj exec

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/sample_app.md

Run the Bootstrap presentation from the host using the project wrapper. The command changes to the src directory and starts runbootstrap on port 8003.

```bash
./runproj exec --command "cd src && ./manage.py runbootstrap --port 8003"
```

--------------------------------

### Configure collapsed screen help with view_help

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/guides/setup_core_crud.md

Set view_help to provide longer screen-level guidance in a collapsed panel. The summary is the clickable bar, details is the expandable text, and color can be 'info' or a hex value. Add "default_open": True to start expanded. The panel uses the 'base' colour and respects view_help_min_width.

```python
class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # …
    view_help = {
        "summary": "About this screen",
        "details": (
            "Use this screen to review active projects.\n\n"
            "Inline fields can be edited directly from the table."
        ),
        "color": "info",
    }
```

--------------------------------

### pcrud_starttemplatepack command - default and Bootstrap 5

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/mgmt_commands.md

Start a new independent template pack from the default DaisyUI template tree, or specify the Bootstrap 5 template tree with --source-template-pack. The first argument is the Python package name, the second is a new or empty destination directory (refuses to overwrite populated directories).

```bash
# Start from the default DaisyUI template tree.
python manage.py pcrud_starttemplatepack my_powercrud_pack ../my-powercrud-pack

```

```bash
# Start from the Bootstrap 5 template tree instead.
python manage.py pcrud_starttemplatepack my_powercrud_pack ../my-powercrud-pack \
  --source-template-pack bootstrap5
```

--------------------------------

### async_task_lifecycle hook example

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/hooks.md

Override async_task_lifecycle in a subclass of AsyncManager to trigger side effects on task status changes. The example checks for the 'fail' event and calls report_error with the task name and result.

```python
class NotificationsAsyncManager(AsyncManager):
    def async_task_lifecycle(self, event, task_name, **kwargs):
        if event == "fail":
            report_error(task_name, kwargs.get("result"))
```

--------------------------------

### Examples of pcrud_extract_tailwind_classes with options

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/mgmt_commands.md

Shows how to use the command with settings configuration, override the output path, and specify an exact output file.

```bash
# Using settings configuration
python manage.py pcrud_extract_tailwind_classes

# Override with command line
python manage.py pcrud_extract_tailwind_classes --output ./static/css/

# Specify exact output file
python manage.py pcrud_extract_tailwind_classes --output ./tailwind/safelist.json
```

--------------------------------

### field_queryset_dependencies example with genres

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/guides/forms.md

Example configuration that restricts the 'genres' child field based on the 'author' parent field, filters by authors lookup, orders by name, and shows all options when parent is empty.

```python
field_queryset_dependencies = {
    "genres": {
        "depends_on": ["author"],
        "filter_by": {"authors": "author"},
        "order_by": "name",
        "empty_behavior": "all",
    }
}
```

--------------------------------

### Broad defaults comparison: Base Configuration API vs PowerField

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/guides/structured_api/powerfields.md

Tabbed example showing the equivalent legacy base configuration (fields/exclude/detail_fields) and the PowerField approach with PowerOverride. The PowerField version explicitly opts into broad defaults and excludes description from the list.

```python
fields = "__all__"
exclude = ["description"]
detail_fields = "__all__"
```

```python
power_fields = [
    PowerOverride(list="__all__", detail="__all__"),
    PowerField("description", exclude={"list": True}),
]
```

--------------------------------

### Run migrations

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/sample_app.md

Runs Django's migrate command to apply database migrations for the sample app.

```bash
./manage.py migrate
```

--------------------------------

### persist_bulk_update backend example

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/hooks.md

Override persist_bulk_update in a subclass of BulkUpdatePersistenceBackend to provide custom bulk update persistence. The example delegates to a ProjectBulkUpdateService, passing the queryset, fields, field data, context, and progress callback.

```python
class ProjectBulkUpdateBackend(BulkUpdatePersistenceBackend):
    def persist_bulk_update(
        self,
        *,
        queryset,
        bulk_fields,
        fields_to_update,
        field_data,
        context,
        progress_callback=None,
    ):
        return ProjectBulkUpdateService().apply(
            queryset=queryset,
            fields_to_update=fields_to_update,
            field_data=field_data,
            mode=context.mode,
            task_name=context.task_name,
            progress_callback=progress_callback,
        )
```

--------------------------------

### get_bulk_choices_for_field hook example

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/hooks.md

Override this hook to filter the queryset of choices for a related field in bulk-edit dropdowns. The example filters the 'owner' field to only active records. Returns a queryset or None for non-relation fields.

```python
def get_bulk_choices_for_field(self, field_name, field):
    queryset = super().get_bulk_choices_for_field(field_name, field)
    if field_name == "owner" and queryset is not None:
        return queryset.filter(active=True)
    return queryset
```

--------------------------------

### Configure row-actions column position and stickiness

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/guides/setup_core_crud.md

Set row_actions_column_position to "start" and row_actions_column_sticky to True to keep row actions near the logical start and pinned during horizontal scrolling. Defaults are "end" and True.

```python
class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # ...
    row_actions_column_position = "start"
    row_actions_column_sticky = True
```

--------------------------------

### Example summary output from pcrud_cleanup_async

Source: https://github.com/doctor-cornelius/django-powercrud/blob/main/docs/mkdocs/reference/mgmt_commands.md

Shows the human-readable summary output format, including counts of cleaned and skipped tasks with details.

```text
PowerCRUD Async Cleanup Summary
Active tasks inspected: 3

Cleaned 2 task(s):
  - 9f2b... (completed successfully) [locks=5, progress=1, dashboard=1]
  - 174c... (completed with failure) [locks=3, progress=1, dashboard=1]

Skipped 1 active task(s):
  - 2cd0...: task still running
```