Skip to main content
Coordinate protected assets and catalog publishing with automated preflight safety checks.

​
Usage

dex release <preflight|publish> [args]

​
Subcommands

​
preflight

Run comprehensive validation checks before publishing. 
dex release preflight [--env test|prod]
Flags:
  • --env <test|prod> - Environment for validation (default: test)
What it checks:
1

Entry runtime audit

Validates all non-legacy entries for data integrity, missing fields, and broken references.
2

Protected asset coverage

Ensures every active catalog lookup has corresponding protected asset mappings.
3

Catalog validation

Checks catalog manifest structure, entry linkage, and metadata completeness.
4

Generated HTML security

Scans all generated HTML files for unsafe patterns, XSS risks, and malformed markup.
Exit behavior:
  • Exits with status 0 if all checks pass
  • Exits with non-zero status and descriptive error if any check fails

​
publish

Publish protected assets and catalog to the target environment. 
dex release publish [--env test|prod] [--dry-run] [--no-preflight]
Flags:
  • --env <test|prod> - Target environment (default: test)
  • --dry-run - Preview changes without applying them
  • --no-preflight - Skip preflight checks (emergency use only)
Optional override flags:
  • --api-base <url> - Override base API URL for both assets and catalog
  • --token <token> - Override admin token for both assets and catalog
  • --assets-api-base <url> - Override assets API URL only
  • --assets-token <token> - Override assets admin token only
  • --catalog-api-base <url> - Override catalog API URL only
  • --catalog-token <token> - Override catalog admin token only
Publish order:
1

Preflight (unless --no-preflight)

Runs all validation checks for the target environment.
2

Assets publish

Publishes data/protected.assets.json to the assets API.
3

Catalog publish

Publishes data/catalog.editorial.json to the catalog API.
4

Snapshot sync (non-dry-run)

Writes local catalog snapshot files from published state.

​
Environment variables

Release commands use these environment variables for authentication: Test environment:
  • DEX_ASSETS_ADMIN_TOKEN_TEST
  • DEX_CATALOG_ADMIN_TOKEN_TEST
Production environment:
  • DEX_ASSETS_ADMIN_TOKEN_PROD
  • DEX_CATALOG_ADMIN_TOKEN_PROD
Shared fallbacks:
  • DEX_ASSETS_ADMIN_TOKEN
  • DEX_CATALOG_ADMIN_TOKEN
Export these tokens in your shell profile or .envrc file. Never commit secrets to the repository.

​
Preflight failures

Preflight fails if:
  • Entry audit failures - Any entry has invalid data, broken recording index refs, or missing required fields
  • Missing asset coverage - Active catalog lookups lack protected asset mappings
  • Active exemptions in prod - Production environment has asset coverage exemptions (prod must have 100% coverage)
  • Catalog validation errors - Catalog manifest has structural issues or linkage failures
  • HTML security violations - Generated HTML contains unsafe patterns detected by scripts/verify-generated-html.mjs

​
Test → Production release

1

Test preflight

dex release preflight --env test
2

Test publish

dex release publish --env test
3

Verify test environment

Manually verify content in test environment.
4

Production preflight

dex release preflight --env prod
5

Production publish

dex release publish --env prod
6

Deploy site

dex deploy --preflight-env prod

​
Dry-run production publish

Preview production changes without applying: 
dex release publish --env prod --dry-run
This runs preflight, computes diffs, but does not publish changes or sync snapshots.

​
Examples

​
Run preflight for production

dex release preflight --env prod

​
Publish to test environment

dex release publish --env test

​
Publish to production with dry-run

dex release publish --env prod --dry-run

​
Emergency publish (skip preflight)

Only use --no-preflight in emergency scenarios with explicit approval.
dex release publish --env prod --no-preflight

​
Override API endpoints

dex release publish --env test --api-base https://staging-api.example.com

​
Override admin tokens

dex release publish --env test --assets-token <token1> --catalog-token <token2>

​
High-risk flags policy

dex release publish --no-preflight is classified as emergency-only under the Dex high-risk flags policy.Production releases should ALWAYS include preflight validation.
From the README:
High-risk flags policy
  1. dex deploy --no-preflight is emergency-only.
  2. dex release publish --no-preflight is emergency-only.
  3. dex catalog manifest remove --force-remove bypasses linkage safety; use only with explicit approval.

​
Preflight output

Successful preflight prints: 
preflight:env=prod
✓ entry audit (42 entries, inventory=42)
✓ protected assets coverage (active=38 mapped=38 exempt=0)
✓ catalog validate
✓ generated html secure checks
release:preflight passed (prod)
Failed preflight prints error details and exits with non-zero status.

​
Publish output

Successful publish prints: 
preflight:passed
release:assets prod hash=a3f8c9e2d1b0 dryRun=no
release:catalog prod hash=b9e4d7c1a8f2 dryRun=no
release:snapshot synced
release:publish complete (prod)

​
Snapshot sync

After successful publish (non-dry-run), the release command writes:
  • data/catalog.snapshot.test.json (for test publishes)
  • data/catalog.snapshot.prod.json (for prod publishes)
These snapshots track the last published state for diffing.

​
Troubleshooting

​
Missing admin token

Error: Missing admin token for assets publish
Solution: Export the appropriate environment variable: 
export DEX_ASSETS_ADMIN_TOKEN_PROD=<your-token>

​
Preflight fails on missing asset coverage

preflight failed: missing protected asset coverage (lookup-abc, lookup-xyz)
Solution: Add asset mappings in the protected assets manager: 
dex assets validate
Then re-run preflight.

​
Active exemptions in prod

preflight failed: prod cannot use active exemptions (lookup-abc)
Solution: Remove exemptions from data/protected.assets.json and add proper asset mappings before publishing to production.

dex deploy

Deploy site after release publish

dex assets

Manage protected assets standalone

dex catalog

Manage catalog entries and metadata

dex entry audit

Audit entry runtime integrity

Build docs developers (and LLMs) love

Get started for freeTalk to us