Skip to main content

​
Overview

The dex init command creates new entry folders with all required metadata, manifests, and generated HTML. You can use either the interactive wizard (TTY mode) or a non-interactive seeded flow.

​
Prerequisites

Before creating entries:
  1. Workspace configured: Run dex setup if this is your first time
  2. Dependencies installed: Run npm i in the repo
  3. Template available: Dex will auto-detect the template from:
    • ./index.html (current directory)
    • entries/test-5/index.html (canonical template)
    • entry-template/index.html (fallback)
If no valid template is found, init will fail with:
No valid template found.
Tried:
- ./index.html: not found
- entries/test-5/index.html: invalid (missing: ...)
Tip: pass --template <path> to force a specific template.

​
Interactive Mode (Wizard)

1

Launch the dashboard

Start Dex in interactive mode:
dex
Or directly launch init:
dex init
2

Complete the wizard steps

The wizard will prompt you for:
  • Title: Entry display name
  • Slug: URL-safe identifier (auto-generated from title)
  • Artist name: Performer name(s)
  • Instruments: One or more instruments (use --quick to skip multiple)
  • Lookup number: Catalog lookup identifier (e.g., LOOKUP-0042)
  • Video source: URL or raw embed HTML
  • Description: Plain text description
  • Series: dex, inDex, dexFest, or none
  • Buckets: Available download buckets (A, B, C, D, E, X)
  • Attribution sentence: Credits attribution text
3

Review and confirm

Dex will:
  • Validate all inputs against schema
  • Generate index.html from the template
  • Create the entry folder with:
    • entry.json (canonical metadata)
    • manifest.json (download manifest skeleton)
    • description.txt (plain text description)
    • index.html (generated HTML)
4

Verify the entry

Run an audit to ensure the entry is valid:
dex entry audit --slug <your-slug>

​
Quick Mode

Skip optional prompts with --quick: 
dex init --quick

​
Open After Creation

Automatically open the generated HTML: 
dex init --open

​
Non-Interactive Mode

For automation, CI/CD, or bulk creation, use a seed JSON file:
1

Create a seed file

Create seed.json with entry data:
{
  "title": "Tim Feeney — Percussion Solo",
  "slug": "tim-feeney",
  "series": "dex",
  "video": {
    "dataUrl": "https://vimeo.com/123456789",
    "dataUrlOriginal": "https://vimeo.com/123456789"
  },
  "sidebarPageConfig": {
    "lookupNumber": "LOOKUP-0042",
    "buckets": ["A", "B"],
    "attributionSentence": "Recorded at Studio XYZ",
    "credits": {
      "artist": ["Tim Feeney"],
      "instruments": ["Percussion"],
      "year": 2025
    }
  }
}
2

Run init with seed

dex init --from ./seed.json --out ./entries
Non-interactive mode requires video.dataUrl in the seed file, or it will fail with:
Video URL is required for non-interactive init. Pass --from with video.dataUrl.

​
Advanced Options

​
Custom Template

Use a specific template file: 
dex init --template ./custom-template.html

​
Custom Output Directory

Write to a different directory: 
dex init --out ./custom-entries

​
Flat Directory Structure

Create entry folder in current directory (no entries/ parent): 
dex init --flat

​
Dry Run

Preview what would be created without writing files: 
dex init --dry-run --from ./seed.json
Output: 
• [dry-run] would write ./entries/tim-feeney/index.html
• [dry-run] would write ./entries/tim-feeney/entry.json
• [dry-run] would write ./entries/tim-feeney/description.txt
• [dry-run] would write ./entries/tim-feeney/manifest.json
Slug: tim-feeney
Template: entries/test-5/index.html

​
Catalog Integration

Link entries to the catalog during creation: Create a catalog entry simultaneously: 
dex init --from ./seed.json \
  --catalog-link create-linked \
  --catalog-status draft \
  --catalog-season S2 \
  --catalog-performer "Tim Feeney" \
  --catalog-instrument "Percussion"

​
Attach to Existing

Link to an existing catalog entry: 
dex init --from ./seed.json \
  --catalog-link attach-existing \
  --catalog-entry-id "entry-123"

​
Catalog Options

  • --catalog-link <mode>: create-linked, attach-existing, or off (default)
  • --catalog-file <path>: Path to catalog.editorial.json
  • --catalog-status <status>: draft, active, or archived
  • --catalog-entry-id <id>: Existing entry ID to attach
  • --catalog-entry-href <href>: Entry href (e.g., /entry/tim-feeney/)
  • --catalog-lookup <number>: Catalog lookup number
  • --catalog-season <season>: Season identifier (e.g., S2)
  • --catalog-performer <name>: Performer name
  • --catalog-instrument <instrument>: Primary instrument

​
Common Errors

Error:
Template not found: ./custom-template.html
Solution: Ensure the template path is correct and the file exists:
ls -la ./custom-template.html
Or omit --template to use auto-detection.
Error:
Template validation failed; missing: dex-sidebar-config, dex-manifest
Solution: Your template is missing required <script> tags with IDs:
  • dex-sidebar-config
  • dex-sidebar-page-config
  • dex-manifest
Use the canonical template as a reference:
dex init --template ./entries/test-5/index.html
Error:
Error: formatZodError(error, 'Sidebar config (wizard step)')
Solution: Your seed data doesn’t match the expected schema. Common issues:
  • Missing required fields (lookupNumber, attributionSentence)
  • Invalid bucket names (must be A, B, C, D, E, or X)
  • Malformed credits structure
Validate your seed JSON structure against the example above.
Error:
Generated HTML failed sanitizer verification: [issues]
Solution: The generated HTML contains forbidden patterns or missing security markers. This usually happens with custom templates. Check:
  • Auth trio scripts are present
  • No legacy Auth0 blocks remain
  • No forbidden runtime script hosts (squarespace, sqspcdn, etc.)
Use the canonical template to avoid sanitization issues.

​
Best Practices

Use Seed Files

For production workflows, always use --from with validated seed files instead of manual input

Validate Immediately

Run dex entry audit --slug <slug> right after creation to catch issues early

Version Control Seeds

Store seed JSON files in version control for reproducibility and audit trails

Test with Dry Run

Use --dry-run to preview changes before committing to file writes

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us