Govard Toolbox

Govard Toolbox

Govard is a containerized development environment orchestrator. This skill provides high-level shortcuts and references.

Quick Reference

Environment Lifecycle

Common Commands

# Start environment
govard up

# Stop environment
govard down

# Stop with volumes (clean slate)
govard down -v

# Shell into PHP container
govard sh

# Run single command
govard sh -c "ls -la"

# View logs
govard logs -f

# Restart services
govard restart

Database Operations

# Connect to MySQL
govard db connect

# Run query -- table names may need a framework-specific prefix (e.g. Magento's
# db.table_prefix in app/etc/env.php, WordPress's $table_prefix) if one is configured
govard db query "SELECT * FROM admin_user LIMIT 1"

# Import dump
govard db import --file backup.sql --drop

# Export database
govard db dump --no-noise -e staging

# Direct sync from remote
govard db import --stream-db -e staging --drop

Remote Sync

# Add remote
govard remote add staging ssh://user@staging.server/path

# Test connection
govard remote test staging

# Sync everything
govard sync --source staging --full

# Plan before sync (preview)
govard sync --source staging --full --plan

# Skip noise (cache, logs)
govard sync --source staging --full --no-noise --no-pii

Bootstrap

# From staging (full setup)
govard bootstrap --clone -e staging --no-pii --no-noise --yes

# Preview plan
govard bootstrap --clone -e staging --plan

Tool Execution

# Run framework CLI
govard tool magento cache:flush
govard tool magerun cache:clear
govard tool artisan migrate
govard tool drush cr

# Node tools
govard tool npm install
govard tool composer install

Services

# Redis
govard redis flush
govard redis cli

# Varnish
govard varnish purge

# Open URLs
govard open app      # Main site
govard open admin    # Admin panel
govard open db       # PHPMyAdmin
govard open mail     # Mailhog

Debugging

# Xdebug control
govard debug on
govard debug off
govard debug status

# Diagnostics
govard diag            # human-readable health report
govard diag --json     # machine-readable verdict — one call answers "is this env healthy"
govard diag --fix      # Auto-fix issues

Agent guidance: before chaining govard ps / govard logs probes, run govard diag --json once and branch on its result; keep down && up escalation for diagnosed failures only.

Connecting an IDE

Xdebug listens on port 9003. govard debug on only enables the extension inside the container — the IDE side still needs to be configured to listen and map paths, or nothing will connect.

VSCode (.vscode/launch.json):

{
    "name": "Listen for Govard Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "pathMappings": { "/var/www/html": "${workspaceFolder}" }
}

PhpStorm: Settings → PHP → Debug → set debug port to 9003; Settings → PHP → Servers → add a server named to match the project, host <project-domain>.test, port 443, debugger Xdebug, path mapping /var/www/html → project directory.

If it still doesn't connect: check govard debug status, confirm the XDEBUG_SESSION cookie matches stack.xdebug_session in .govard.yml, and confirm the IDE is actually listening on 9003 before triggering a request. Disable Xdebug (govard debug off) when not actively debugging — it slows down every request noticeably.

Configuration

The .govard.yml at the project root defines the framework, PHP/Node/DB versions, services, and domain — it's committed to the repo, so no govard init is needed for an existing project. Config is layered (later overrides earlier), and only .govard.yml is writable via govard config set:

The profile name resolves from --profile, else the per-project registry (~/.govard/projects.json), else none — govard config profile shows the active one. Never hand-edit .govard.yml to chase drift warnings while a profile layer is active: diag compares the base file against detected runtime, but the running stack and every audit use the merged config with the profile applied, so a stale base is expected noise, not a bug. Verify with govard config profile (its values must match the running containers) instead of syncing the base — converging the base is a team decision via govard doctor --fix in a real TTY.

project_name: myproject
framework: magento2          # magento2, laravel, symfony, wordpress, nextjs, …
framework_version: 2.4.7
domain: myproject.test
stack:
  php_version: "8.3"
  node_version: "20"
  db_version: "10.6"
  services:
    web_server: apache        # apache | nginx
    db: mariadb               # mariadb | mysql | none
    search: opensearch        # opensearch | elasticsearch | none
    cache: redis              # redis | valkey | none
  features:
    xdebug: false
    varnish: false

# Auto-config after DB sync (rebuilds app-level config, e.g. Magento's env.php)
govard config auto

# Read a value without opening the file
govard config get stack.php_version

# Write a value — only .govard.yml is writable this way
govard config set stack.php_version 8.4

Audit

For generic PHP patterns (strict_types/PSR-12/Composer/PHPStan/PDO) see php-dev-core.

Govard's persistent audit gate for Magento 2/Mage-OS and Laravel/Symfony/WordPress -- see magento2-linter for full Magento policy (target --mode, PHP matrix, provider rules, caching/rerun identity) and this section for the 4-framework matrix. Text streams live like vendor/bin/phpcs (TTY colorized + uncapped, piped capped + plain); json stays a single object on stdout for AI agents. A failed/cancelled run still renders before exiting non-zero.

Audit Matrix — 4 Frameworks

Govard audit run --checks lint --lint-provider govard --mode project --format json is native for all 4 frameworks. Detection is via framework markers; no project-level phpcs.xml/phpstan.neon required for fallback. PHPStan level 5 and linters phpcs + phpstan are fixed across the matrix.

--lint-provider govard is the native provider (alias --provider kept for back-compat but deprecated). Use --mode project for the common case; --mode standalone only for isolated packages, --mode module_in_project only for Magento app/code modules.

On DSH: call govard_audit_lint {worktreePath?} → {lint:{phpcs,phpstan},pubMediaGuard,rawJson,summary}. Do not hand-parse text/exit codes. Otherwise: govard audit run --checks lint --format json (machine-clean, one JSON on stdout, diagnostics on stderr; text mode capped at 10 and colorized — not for agents).

govard audit run --checks lint                    # project or module_in_project, default text streams live
govard audit run --checks lint --format json      # machine-clean for agents, diagnostics on stderr
govard audit run --checks lint,profiler --url https://shop.test/  # also capture profiler CSV (v1.64.0+)
govard audit rerun --session SESSION_ID           # exact rerun by session, profiler URL included
govard audit toolchain status                     # lint image health

--mode validates early (auto, project, module_in_project, standalone) -- typo module fails with unknown audit target mode (valid modes: ...). govard env up/pull now uses resilient per-image pulls (--ignore-buildable, reuse compatible local image or build Govard image locally). Stale diagnostics lease (is already held) -- rm ~/.govard/audit/<project>/leases/diagnostics.json and .govard/*/custom/govard-audit-profiler-*.conf; 7-page manual audit costs ~2.5-3 min on reference project -- keep all 7 with timeout 300 and trap single, not fewer pages.

Lint scope — quick (diff) vs deep (project) — quick vs deep

Lint supports quick (PR) vs deep (release) scope — keep this quick.*deep mapping in sync with magento2-performance-audit's Scope: quick / Scope: deep header.

On DSH: call govard_audit_lint {worktreePath?, scope?: "diff"|"project", base?: "origin/master"} → {lint:{phpcs,phpstan},pubMediaGuard,rawJson,summary}; it already uses scope diff + jobs min(nproc,4) + stale diagnostics cleanup internally. CLI govard audit run now also defaults --lint-jobs min(nproc,4) (4 on typical 12-core, was 2) and scope diff lints only changed files via diff-files.txt mounted as GOVARD_LINT_DIFF_FILE (php/phtml under target, vendor/generated/var/pub/media excluded, empty diff short-circuits as passed with diff-empty cache). Otherwise: shell govard audit run --checks lint --scope diff --base origin/master --format json (quick, ~3-5s for 1 file vs 9m full) or --scope project --format json (deep). Text mode caps at 10 and is colorized — use --format json for agents and never hand-parse text/exit codes. For workflow-level lint quick/deep, prefer govard_audit_lint on DSH and govard audit run --checks lint --scope diff --base origin/master otherwise — keep skills vs plugins separate (A).

Timeout — use govard's auto (default), never shell timeout: since v1.67.0 govard audit has --timeout auto (default, 90s–30m framework-aware: 80ms/file magento2, 70ms wordpress, 20ms symfony/laravel + 60s base + 50% headroom, at least 15m for magento2/wordpress since v1.68.0 — was 10m). Verified 2026-08-29 + 2026-08-31: symfony 11k files → 2m15s auto, wordpress fresh 1.5k → ~4m, large wordpress 8k → 15m auto (actual 219s/450s), large magento2 10k non-vendor → 30m auto (actual 590s cold / 178s warm, 1197s cold for 20k findings). Never wrap govard audit with shell timeout 120/300 — it causes cancelled + orphan govard-audit-* containers + stale ~/.govard/audit/<id>/lock (v1.68.0 auto-removes stale lock if mtime>10m or holder PID dead, but still wastes run). Govard's internal context.WithTimeout cancels cleanly and prints INFO audit timeout 2m15s (auto-estimated…) in text (silent in json). Override only when needed: --timeout 300s/10m/0 (no limit); default auto is correct for all 4 frameworks — example-magento2/example-wordpress failed at timeout 120 in 2026-08-31 validation because outer timeout killed auto's 15m estimate.

Toolchain & image — verify after build: after make build (which embeds ContextDigest SHA256 of docker/audit/Dockerfile+bin+toolchains+tests), run govard audit toolchain build then govard audit toolchain status must show Present: yes and same Context digest. Runner is bin/glint (/usr/local/bin/glint). Since v1.67.0 the toolchain natively bundles WPCS 3.4.1 + Symfony CS 3.16.0 via composer global config allow-plugins then installed_paths fallback, and RestrictedCodeSniff.php is patched file_exists ? include : [] (commit 2011f24) because magento-coding-standard 40 (used on php 8.1+) may ship without _files/restricted_classes.php per-toolchain. Quick check: docker run --rm govard-local/glint:… /opt/govard/toolchains/php-8.3/vendor/bin/phpcs -i must list WordPress, Symfony, Magento2. Wrong ENTRYPOINT on docker commit gives sh: Illegal option -- — always commit --change='ENTRYPOINT ["/usr/local/bin/glint"]'. Lock audit lock ... already held (waited 30s) → rm -f ~/.govard/audit/<projectId>/lock + docker rm -f govard-audit-* if holder crashed (since v1.68.0 stale lock auto-removed if mtime>10m or holder PID dead). Global govard 1.65.0 != bin 1.67.0 → manual sudo cp govard/bin/govard /usr/local/bin/govard (approval prompts disabled, TTY required).

Detailed References

See bundled documents:

• COMMANDS.md - Exhaustive command reference
• GUIDES.md - Case studies and patterns
• FAQ.md - Troubleshooting

For Magento-specific: Load govard-magento skill For Laravel-specific: Load govard-laravel skill