Warden Agent Skill

Warden is a local wrapper for docker-compose that automates DNS (dnsmasq), reverse proxy (Traefik), and webmail (Mailpit). Project .env drives ephemeral docker-compose.yml generation. Preview with warden env config.

Quick Start

warden env-init myproject magento2   # Initialize project
warden svc up -d                     # Start global services (Traefik, DNS, Mailpit)
warden env up -d                     # Start project containers
warden shell                        # Interactive shell in php-fpm

Environment Lifecycle

| Command | Purpose | Example | |---------|---------|---------| | warden env-init | Initialize new project | warden env-init mystore magento2 | | warden env up | Start environment | warden env up -d | | warden env down | Stop environment | warden env down | | warden env config | Preview docker-compose | warden env config | | warden env ps | List containers | warden env ps | | warden env pull | Pull images | warden env pull | | warden env logs -f nginx | Follow logs | warden env logs -f nginx | | warden env exec php-fpm bash | Exec into container | warden env exec php-fpm bash |

Database Operations

| Command | Purpose | Example | |---------|---------|---------| | warden db connect | Interactive MySQL | warden db connect | | warden db import | Import SQL dump | See patterns below | | warden db dump | Export database | warden db dump > backup.sql | | warden db upgrade | Upgrade MariaDB/MySQL | warden db upgrade |

Import patterns (preferred for large dumps):

pv dump.sql.gz | gzip -d | warden db import
gzip -dc dump.sql.gz | warden db import
warden db import < database.sql

Shell Access

| Command | Purpose | |---------|---------| | warden shell | PHP-FPM container shell (default: bash) | | warden debug | Xdebug-enabled shell (use for debugging) | | warden blackfire | Blackfire profiler: warden blackfire run php script.php | | warden spx | PHP SPX profiler |

Important: Use warden debug (not warden shell) when debugging with Xdebug.

Service Management

| Command | Purpose | |---------|---------| | warden svc up -d | Start global services | | warden svc down | Stop global services | | warden svc ps | List global services | | warden status | List running environments |

File Sync (macOS)

| Command | Purpose | |---------|---------| | warden sync start | Start Mutagen sync | | warden sync monitor | Monitor sync status | | warden sync flush | Flush sync | | warden sync reset | Reset sync |

Redis / Valkey

warden redis              # Interactive Redis CLI
warden redis FLUSHALL      # Execute command
warden valkey              # Valkey (Redis alternative)

Environment Types

Supported: magento2, magento1, laravel, symfony, wordpress, drupal, shopware, cakephp, local. See references/environments.md.

Key .env Variables

Project .env controls services and versions. See references/env-variables.md for full reference.

| Variable | Description | |----------|-------------| | WARDEN_ENV_NAME | Unique project identifier | | WARDEN_ENV_TYPE | Environment type | | TRAEFIK_DOMAIN | Base domain (default: {name}.test) | | PHP_VERSION | PHP version (7.4, 8.1–8.4) | | WARDEN_DB, WARDEN_REDIS, etc. | Service toggles (1/0) | | MYSQL_DISTRIBUTION_VERSION | MariaDB/MySQL version |

Service Name Mapping

| .env Variable | Container Name(s) | |---------------|-------------------| | WARDEN_DB=1 | db | | WARDEN_REDIS=1 | redis | | WARDEN_OPENSEARCH=1 | opensearch | | WARDEN_ELASTICSEARCH=1 | elasticsearch | | WARDEN_VARNISH=1 | varnish | | WARDEN_RABBITMQ=1 | rabbitmq | | WARDEN_NGINX=1 | nginx | | PHP_VERSION | php-fpm, php-debug |

Global Services & URLs

Default domain: warden.test. Configure in ~/.warden/.env (WARDEN_SERVICE_DOMAIN).

| Service | URL | |---------|-----| | Traefik Dashboard | https://traefik.warden.test | | Webmail (Mailpit) | https://webmail.warden.test | | Portainer | https://portainer.warden.test | | phpMyAdmin | https://phpmyadmin.warden.test |

Email (Mailpit): No SMTP config needed. Warden routes sendmail to Mailpit. All emails at https://webmail.warden.test.

Framework Compatibility

For "match Magento 2.4.8 requirements" requests:

1. Search official docs for system requirements
2. Map to .env: PHP → PHP_VERSION, DB → MYSQL_DISTRIBUTION_VERSION, etc.
3. Update .env with matched versions

Agent Behavior Examples

Generate service table: Read .env, map WARDEN_* variables to service status, output table (Service | Status | Version).

Verify PHP running: Run warden env ps, check for php-fpm, php-debug, php-blackfire.

Troubleshoot non-loading site: warden svc ps → warden env ps → ping app.{project}.test → warden env logs nginx.

Xdebug not working: Use warden debug, verify IDE server name {project}-docker, port 9003, XDEBUG_SESSION cookie.

References

• references/commands.md – Full command reference
• references/environments.md – Environment types
• references/env-variables.md – .env variable reference
• references/global-services.md – Service URLs and config
• references/troubleshooting.md – Common issues and solutions
• examples/workflows.md – Workflow examples