CLI Reference

On this page

Overview

Canopy uses cargo xtask for project automation. All commands are defined in xtask/src/cmd/ and run via:

cargo xtask <command> [flags]

dev — Devstack Management

Manages the Docker Compose development environment (per ADR-005 deployment profiles).

dev start

Start the local development environment.

cargo xtask dev start [--shared-db] [--profile <name>]
Flag Description

--shared-db

Use a single PostgreSQL instance for all databases (saves resources)

--profile <name>

Deployment profile: snap-only, tanf-only, medicaid-chip, caps-only, wic-only, full (default: full)

Runs the staleness guard to detect changes since last start. Creates SHA-256 markers in .devstack/ for source, dependencies, Dockerfile, compose, migrations, and seed data.

dev stop

Stop containers but preserve data volumes.

cargo xtask dev stop

dev reload

Rebuild changed services and restart. Preserves data volumes.

cargo xtask dev reload [--shared-db] [--profile <name>]

dev restart

Wipe all data and start completely fresh (equivalent to clean + start --no-cache).

cargo xtask dev restart [--shared-db] [--profile <name>]

dev refresh

Auto-detect what changed and perform the minimum rebuild/restart. Uses the staleness guard to compare SHA-256 markers against current state:

  • Source changes (.rs files) → rebuild affected services

  • Dependency changes (Cargo.lock) → full rebuild

  • Dockerfile changes → rebuild images

  • Docker Compose changes → recreate containers

  • Migration changes → restart services (migrations run on startup)

  • Seed data changes → re-seed databases

cargo xtask dev refresh

dev status

Show running services with ports and health check status.

cargo xtask dev status

dev clean

Stop containers and wipe ALL data volumes. Requires confirmation.

cargo xtask dev clean --confirm

dev logs

Follow container logs. Optionally filter to a single service.

cargo xtask dev logs [service-name]

test — Test Suite

Runs format check, clippy, and cargo-nextest (capped at 8 threads to avoid devstack saturation).

cargo xtask test [--unit] [--integration] [--no-refresh]
Flag Description

--unit

Run only unit tests (lib + bin tests, no devstack required)

--integration

Run only integration tests (tests/ directory, requires devstack)

--no-refresh

Skip automatic devstack refresh before integration tests

Without flags, runs both unit and integration tests. Integration tests use infrastructure_available() guard — skips gracefully when devstack is down (unless CANOPY_CI=true, then panics).

e2e — End-to-End Tests

Runs Playwright E2E tests against the running devstack. The bare, unfiltered invocation is the blocking pre-push battery (#1386): it defaults to the full devstack profile, requires the test-clock build (probed before the suite), and fail-loud-verifies the journey lane afterwards (>0 executed, 0 skipped, fresh walkthrough artifacts — see Testing). Any trailing Playwright filter or --devstack-profile snap-only marks the run as targeted and skips the gate.

cargo xtask e2e [--no-refresh] [--devstack-profile full|snap-only] [--visual] [--capture] [-- <playwright-args>]
Flag Description

--no-refresh

Skip automatic devstack refresh before E2E tests

--devstack-profile

Compose profile to bring up/target; full (default) is the battery’s standing requirement, snap-only the targeted opt-out

--seed / --households

Pin the generative seed dataset for reproduction

--visual

Define the on-demand vb-* visual-baseline capture projects

--capture

Define the opt-in screenshot/capture projects (screenshots, demo-review, demo-review-dark, multi-size-screenshots)

-- <args>

Extra arguments forwarded to Playwright (e.g., --headed, --grep "search")

Examples:

cargo xtask e2e                       # The blocking battery (full profile + test-clock)
cargo xtask e2e -- --headed           # Targeted: visible browser (gate skipped)
cargo xtask e2e -- --grep "dashboard" # Targeted: only matching tests
cargo xtask e2e --no-refresh --capture -- --project demo-review  # capture sweep

validate — Pre-Push Validation

Comprehensive validation run by the pre-push hook. Checks everything needed before code reaches CI.

cargo xtask validate [--skip-docker] [--timing]
Flag Description

--skip-docker

Skip Docker build validation (faster, used when only docs change)

--timing

Print per-step timing breakdown for debugging slow runs

Steps (in order):

  1. Repository visibility check (must be public)

  2. Commit signing configuration check

  3. Mandatory docs check (Tier 3 files exist and are non-empty)

  4. SPDX header check on .rs files

  5. cargo deny check (advisories + licenses + bans)

  6. cargo fmt --check

  7. cargo clippy --profile test (shares compilation cache with nextest)

  8. cargo nextest run (8 threads)

  9. Docker build validation (unless --skip-docker)

check-docs — Tier 1 Doc Integrity

Verifies that Tier 1 (universal) docs match the upstream template by comparing SHA-256 hashes.

cargo xtask check-docs [--fix [--yes]]
Flag Description

--fix

Download and overwrite drifted Tier 1 docs from the template. Shows a diff summary.

--yes

Skip confirmation prompt when using --fix (for CI use). Requires --fix.

Template source: gitlab.com/gadhs/templates/claude-quickstart — synced .claude/rules/ digests + docs/modules/standards/ pages (see .claude/sync-manifest.toml).

seed — Database Seeding

Seeds the devstack databases with deterministic test data for development and E2E testing.

cargo xtask seed [--seed <number>] [--households <count>] [--jurisdiction <name>]
Flag Default Description

--seed

(random)

RNG seed for deterministic output

--households

9

Number of households to generate

--jurisdiction

georgia

Jurisdiction name (must match a directory under rulesets/)

api-docs — OpenAPI Snapshot Diffing

Fetches OpenAPI JSON from all running services and compares against committed snapshots.

cargo xtask api-docs [--update]

Fetches from http://localhost:{port}/api-doc/openapi.json for each of the 11 API services. Reports path count differences, schema changes, and new/removed endpoints.

With --update: overwrites snapshots in test-results/openapi/ to accept current specs.

gen-signing-keys — ECDSA Key Generation

Generates an ECDSA P-256 signing key pair for determination signing (ADR-002).

cargo xtask gen-signing-keys --program <name> [--output-dir <path>]
Flag Default Description

--program

(required)

Program name: snap, tanf, medicaid, chip, caps, wic

--output-dir

.keys

Output directory for PEM files

Produces two files: * {output-dir}/{program}-private.pem — PKCS#8 private key (set as CANOPY_{PROGRAM}__SIGNING_KEY) * {output-dir}/{program}-public.pem — SPKI public key (set as CANOPY_VERIFY_KEY_{PROGRAM})

perf — Performance Testing

Runs k6 performance tests against the devstack.

cargo xtask perf [--profile <type>] [--service <name>] [--save-baseline <name>]
Flag Default Description

--profile

smoke

Test profile: smoke, load, stress, soak

--service

(all)

Target a specific service

--save-baseline

—

Save results as a named baseline for comparison

init — Project Initialization

Initialize a new project from the claude-quickstart template. Used once during initial project setup.

cargo xtask init --name <project-name> --group <gitlab-group> --owner <username> [--security-contact <email>]

Not used in day-to-day development.

Edit this page · default