Developer Commands

Hegemony uses Task as the canonical command runner: if CI or pre-commit runs a check, it is runnable through a task listed here. Descriptions come from the Taskfiles' desc: fields.

Root tasks

Command	Description
task check:file-permissions	Verify source file permissions (canonical entrypoint for pre-commit/CI)
task py:format	Format Python (ruff)
task py:lint	Lint Python (ruff)
task py:lint:fix	Lint+fix Python (ruff)
task py:typecheck	Check Python types (ty)
task py:typecheck:strict	Check Python types strictly (fail on warnings)
task py:all	Python format + lint + typecheck (ty)
task ui:install	Install UI dependencies (npm ci)
task ui:format	Format UI (oxfmt)
task ui:format:check	Check UI formatting (oxfmt)
task ui:lint	Lint UI (oxlint)
task ui:lint:fix	Lint+fix UI (oxlint)
task ui:lint:css	Lint CSS (stylelint)
task ui:lint:css:fix	Lint+fix CSS (stylelint)
task ui:lint:tailwind	Lint Tailwind classes (eslint-plugin-tailwindcss)
task md:lint	Lint Markdown (markdownlint-cli2)
task md:lint:fix	Lint+fix Markdown (markdownlint-cli2)
task docs:check-links	Verify local doc links and docs/*.md references from code resolve
task docs:screenshots	Regenerate documentation screenshots (docs/assets/screenshots/) from the docs-shots manifest
task docs:generate	Regenerate the docs index, docs/reference/ pages, and the UI help-content module
task docs:verify-sync	Verify generated reference docs are in sync (fails if out of date)
task docs:verify-claims	Verify factual claims in Markdown docs against sources of truth
task docs:fixtures:refresh	Refresh the step-handler catalog fixture from the installed plugin wheels
task docs:verify-fixtures	Verify the step-handler fixture matches the installed plugin wheels
task docs:all	Run every documentation check (lint, links, sync, claims, fixtures, meta-tests)
task ui:typecheck	Typecheck UI (tsc)
task ui:e2e:install	Install Playwright browsers using the locked UI dependency
task ui:e2e:install:deps	Install Playwright Chromium browser and Linux OS dependencies (may prompt for sudo)
task ui:e2e	Run all UI E2E tests
task ui:e2e:smoke	Run UI E2E smoke tests only (@smoke, chromium)
task ui:e2e:coverage	Run UI E2E tests with V8 coverage and generate reports
task ui:all	UI format check + lint + CSS lint + Tailwind lint + typecheck + api-headers + contract-types + page-docs
task ui:check:api-headers	Check UI API client includes Authorization headers
task ui:check:contract-types	Check contract.ts has no manually defined types (must re-export from generated api-types)
task ui:check:page-docs	Check every page component under apps/ui/src/pages carries a doc block
task ui:regenerate-types-from-api	Generate TypeScript types from API OpenAPI spec
task ui:verify	Verify UI (lint/typecheck + build + Playwright smoke E2E)
task precommit	Run pre-commit on all files
task precommit:hook	Run a specific pre-commit hook by id (usage: task precommit:hook -- <hook-id>)
task commit:lint	Lint the last commit message with commitlint (mirrors CI commit-lint job)
task test	Run Python tests in parallel (pytest-xdist, loadfile)
task test:serial	Run Python tests serially (debug-friendly)
task test:auth	Run auth tests (route coverage, role matrix, security audit)
task test:auth:route-coverage	Verify all API routes require auth
task test:audit	Run audit-log tests (vocabulary, coverage registry, emitter reachability, write path)
task test:audit:coverage	Verify every mutating route carries an audit decision and reaches an audit emitter
task test:schema	Run schema alignment tests only
task test:cov	Run Python tests with coverage in parallel (pytest-xdist, loadfile)
task test:cron-compat	Test cron expression compatibility between cronsim (backend) and cronstrue (frontend)
task test:cron-compat:strict	Test cron compatibility (fail on validation mismatches)
task py:vulture	Find dead Python code (vulture)
task api:openapi:lint	Lint OpenAPI schema (Spectral)
task docker:lint	Lint Dockerfiles (hadolint via Docker)
task py:licenses	Check Python dependency licenses
task py:licenses:check	Verify Python licenses against allowlist
task ui:licenses	Check UI dependency licenses
task ui:licenses:check	Verify UI licenses against allowlist
task licenses:images	Verify every container image in deploy/ is licence-reviewed
task licenses:plugins	Verify the pinned plugin repositories' own licences and run their image licence gates
task licenses:notices	Regenerate the per-package third-party attribution list
task licenses:python	Refresh the declared licence of every PyPI distribution uv.lock pins
task licenses:python:verify	Verify the licence map still covers every distribution uv.lock pins
task sbom:generate	Regenerate the CycloneDX bills of materials and licence summary under sbom/
task sbom:verify	Verify the committed bills of materials and licence summary are in sync
task sbom:refresh-spdx	Refresh the vendored SPDX licence identifiers from the CycloneDX schema
task licenses:all	Verify all dependency licenses
task reuse:lint	Verify REUSE 3.3 (SPDX) compliance for source files
task reuse:annotate	Add SPDX header to file(s). Usage: task reuse:annotate -- path/to/file [more...]
task py:security	Security scan Python (bandit)
task py:audit	Audit Python dependencies for vulnerabilities
task ui:audit	Audit UI dependencies for high/critical vulnerabilities
task ui:audit:fix	Fix UI audit vulnerabilities and normalize lockfile
task security:all	Run all security checks (bandit + pip-audit + npm audit + trivy)
task security:trivy:iac	Scan IaC (Dockerfiles, compose) for misconfigurations (trivy via Docker)
task security:trivy:images	Scan Docker images for vulnerabilities (trivy via Docker, requires built images)
task security:semgrep	Run Semgrep security analysis (via Docker)
task api:export-openapi	Export OpenAPI spec to deterministic JSON file (requires API container running on port 8000)
task api:export-openapi-local	Export OpenAPI spec without running containers (uses uv, no DB/Temporal needed)
task api:regenerate	Export OpenAPI spec locally, lint, and regenerate TypeScript types (no containers needed)
task api:verify-openapi-sync	Verify openapi.json is in sync with API code (fails if out of date)
task api:verify-types-sync	Verify generated TypeScript API types/defaults are in sync (fails if out of date)
task db:migrate	Run database migrations (alembic upgrade head)
task db:migrate:prod	Run database migrations in prod compose
task db:revision	Create a new migration revision
task db:current	Show current migration revision
task db:history	Show migration history
task db:heads	Show current migration head(s)
task db:downgrade	Downgrade one migration
task lint	Run all linters + typechecks (Python + UI + Markdown)
task fmt	Run all formatters (Python + UI)
task check	Full local check (pre-commit + pytest)
task smoke:api	Smoke test API /health (with retry)
task smoke:ui	Smoke test UI is reachable (with retry)
task smoke:otel	Smoke test OTel collector health endpoint (with retry)
task dev:up	Rebuild dev stack and run smoke tests
task dev:up:nocache	Rebuild dev stack and run smoke tests (no cache)
task dev:down	Stop dev stack
task prod:up	Start production stack (shorthand for compose:prod:up)
task prod:down	Stop production stack (shorthand for compose:prod:down)
task prod:ps	Show production stack status
task prod:logs	Follow production logs
task vault:up	Forward to hegemony-demo-data: compose:vault:up
task vault:down	Forward to hegemony-demo-data: compose:vault:down
task vault:logs	Forward to hegemony-demo-data: compose:vault:logs
task vault:status	Forward to hegemony-demo-data: compose:vault:status
task vault:reset	Forward to hegemony-demo-data: compose:vault:reset
task release:cut	Create a release branch from develop (usage: task release:cut -- X.Y.Z)
task release:finish	Back-merge main into develop after a release
task release:verify-version-sync	Verify release/runtime/OpenAPI/UI version metadata are in sync
task release:manifest:check	Verify the plugin pins, sibling checkouts and pyproject version floors are consistent (offline)
task release:manifest:build	Build hegemony-release.json from the pins and the plugin release tags (strict; needs the plugin repos)
task release:floors:sync	Move the hegemony-* version floors in pyproject.toml to the pinned plugin versions and refresh uv.lock

Compose stack tasks

Compose tasks live in deploy/compose/Taskfile.yml and are invoked through the compose: namespace.

Command	Description
task compose:dev:up	Run migrations and start dev stack. Use SERVICES=core|auth,s3,otel,https,openbao-internal
task compose:dev:down	Stop dev stack
task compose:dev:ps	Show dev stack status
task compose:dev:logs	Follow dev logs (all or specific service)
task compose:dev:build	Build dev images
task compose:dev:rebuild	Rebuild dev images and restart
task compose:dev:rebuild:nocache	Rebuild dev images (no cache) and restart
task compose:dev:restart	Restart dev services
task compose:dev:exec	Execute command in a dev container
task compose:dev:reset	DANGER: Stop dev stack and remove volumes (wipes DBs; a bind-mounted HEGEMONY_S3_DATA_HOST_DIR is left in place)
task compose:dev:config	Show resolved dev compose config (useful for debugging overlays)
task compose:prod:up	Run migrations and start prod stack. Use SERVICES=core|auth,s3,otel,https,openbao-internal|...,prod-local
task compose:prod:down	Stop prod stack
task compose:prod:ps	Show prod stack status
task compose:prod:logs	Follow prod logs (all or specific service)
task compose:prod:build	Build prod images (requires prod-local overlay)
task compose:prod:rebuild	Rebuild prod images from source and restart
task compose:prod:exec	Execute a command in a prod container (e.g. -- temporal tctl ... )
task compose:prod:restart	Restart prod services
task compose:prod:config	Show resolved prod compose config (useful for debugging overlays)
task compose:prod:reset	DANGER: Stop prod stack and remove volumes (wipes DBs; a bind-mounted HEGEMONY_S3_DATA_HOST_DIR is left in place)
task compose:objectstore	Backup/restore the bundled object store + related DB metadata (xattr-preserving). Usage: ACTION=backup|restore ENV=dev|prod DB_SCOPE=storage|full BACKUP=/path/file.tar.gz CONFIRM=restore, plus the SERVICES, BUILD and EXTRA_FILES the stack runs with
task compose:dev:rebuild:api	Rebuild API image and restart it
task compose:dev:rebuild:ui	Rebuild UI image and restart it
task compose:dev:rebuild:worker	Rebuild worker image and restart it
task compose:dev:rebuild:scheduler	Rebuild scheduler image and restart it
task compose:dev:ui:clean	Clean UI node_modules volume and rebuild
task compose:dev:auth:disable	Disable authentication (modify .env.dev and restart API)
task compose:dev:auth:enable	Enable authentication (modify .env.dev and restart API)
task compose:dev:auth:status	Show current authentication status from running API container
task compose:demo:plugins:fetch	Forward to hegemony-demo-data: compose:demo:plugins:fetch
task compose:demo:plugins:pin	Forward to hegemony-demo-data: compose:demo:plugins:pin
task compose:demo:plugins:build	Forward to hegemony-demo-data: compose:demo:plugins:build
task compose:demo:up	Forward to hegemony-demo-data: compose:demo:up
task compose:demo:local:up	Forward to hegemony-demo-data: compose:demo:local:up
task compose:demo:exec	Forward to hegemony-demo-data: compose:demo:exec
task compose:registry:ui:dev	Open the dev platform registry console on 127.0.0.1 (Ctrl-C closes it)
task compose:registry:ui:prod	Open the prod platform registry console on 127.0.0.1 (Ctrl-C closes it)
task compose:objectstore:ui:dev	Open the dev object store browser on 127.0.0.1 (Ctrl-C closes it)
task compose:objectstore:ui:prod	Open the prod object store browser on 127.0.0.1 (Ctrl-C closes it)
task compose:objectstore:ui:demo	Forward to hegemony-demo-data: compose:objectstore:ui:demo
task compose:openbao:ui:dev	Open the dev OpenBao UI on 127.0.0.1 (needs a token; Ctrl-C closes it)
task compose:openbao:ui:demo	Forward to hegemony-demo-data: compose:openbao:ui:demo
task compose:openbao:token:dev	Print a short-lived OpenBao UI token for the dev stack (hegemony-api policy)
task compose:openbao:token:demo	Forward to hegemony-demo-data: compose:openbao:token:demo
task compose:temporal:ui:dev	Open the dev Temporal console on 127.0.0.1 (unauthenticated, every org; Ctrl-C closes it)
task compose:temporal:ui:prod	Open the prod Temporal console on 127.0.0.1 (unauthenticated, every org; Ctrl-C closes it)
task compose:temporal:ui:demo	Forward to hegemony-demo-data: compose:temporal:ui:demo
task compose:demo:down	Forward to hegemony-demo-data: compose:demo:down
task compose:demo:reset	Forward to hegemony-demo-data: compose:demo:reset
task compose:demo:logs	Forward to hegemony-demo-data: compose:demo:logs
task compose:demo:ps	Forward to hegemony-demo-data: compose:demo:ps
task compose:vault:up	Forward to hegemony-demo-data: compose:vault:up
task compose:vault:down	Forward to hegemony-demo-data: compose:vault:down
task compose:vault:logs	Forward to hegemony-demo-data: compose:vault:logs
task compose:vault:status	Forward to hegemony-demo-data: compose:vault:status
task compose:vault:reset	Forward to hegemony-demo-data: compose:vault:reset