Invoke Runner Skill
Python Invoke task automation for the DTX website project.
Documentation References (Single Source of Truth)
For complete command reference, consult these mkdocs files:
| Document | Content |
|---|
docs/development/invoke-tasks.md | Complete invoke command reference |
docs/development/backend-quickstart.md | Backend development quickstart |
docs/development/testing.md | Testing procedures including worktree verification |
Running Invoke Commands
Method 1: PATH Prefix (Recommended for Claude)
When bash hooks block source commands, prepend the venv bin to PATH:
PATH=".venv/bin:$PATH" inv <command>
For worktrees, use the full path:
PATH="/path/to/worktree/.venv/bin:$PATH" /path/to/worktree/.venv/bin/inv <command>
Method 2: Poetry Run
poetry run inv <command>
Method 3: Activate venv
source .venv/bin/activate
inv <command>
Why PATH Matters
Invoke tasks call python manage.py or other Python commands. Without venv bin in PATH:
/bin/bash: line 1: python: command not found
PATH prefix ensures subprocess calls find the correct Python interpreter.
Key Patterns
Run vs Exec
run - One-off command in NEW container (with --rm):
inv test.run --cmd 'python manage.py test app.tests -v 2'
exec - Command in RUNNING container:
inv dev.exec backend 'python manage.py shell'
Environment-Specific Commands
All environments (dev, test, prod) support:
inv <env>.up # Start
inv <env>.down # Stop and remove
inv <env>.logs # Follow logs
inv <env>.run --cmd '<cmd>' # One-off command
Database Operations
inv db.migrate.all # Migrations for all environments
inv db.migrate.test # Test environment only
inv db.populate.all # Reset and populate test DB
Adding a new Django app: inv db.migrate.* runs
python manage.py makemigrations <apps> with an explicit app list
defined at backend/tasks.py::apps (it does NOT auto-discover from
INSTALLED_APPS). When you scaffold a new app, append it there too —
otherwise makemigrations silently skips it. Reference impl:
the user app entry in
backend/tasks.py:27. Registering in settings.INSTALLED_APPS
covers migrate but not makemigrations in this project.
Testing (Docker - Recommended)
Avoid Redis hanging issues by running tests in Docker:
inv test.run --cmd 'python manage.py test app.tests -v 2'
Cypress E2E
inv test.setup # Full setup
inv test.spec --spec navigation # Specific spec
inv test.headless # All tests headless
Worktree Workflow
From worktree root:
cd /path/to/worktree
PATH=".venv/bin:$PATH" inv test.down
PATH=".venv/bin:$PATH" inv test.setup
PATH=".venv/bin:$PATH" inv db.migrate.test
PATH=".venv/bin:$PATH" inv db.populate.all
PATH=".venv/bin:$PATH" inv test.up
Common Issues
| Issue | Solution |
|---|
python: command not found | Use PATH prefix method |
| Redis connection errors | Use Docker: inv test.run --cmd '...' |
| Tests hang on cleanup | Use Docker: inv test.run --cmd '...' |
| Module not found | Ensure correct venv is activated |
When Modifying Tasks
Update these files when changing invoke tasks:
docs/development/invoke-tasks.md (primary reference)docs/development/backend-quickstart.md (if backend-related)