Overview
The Dex CLI provides a Terminal User Interface (TUI) dashboard for interactive entry management and content operations. The TUI is built with Ink (React for CLIs) and offers a full-screen menu system with keyboard navigation.Launch the dashboard with
dex (no arguments) or dex dashboard.Dashboard Layout
- Header: Logo, version, workspace info
- Workspace: Command menu or active wizard/manager
- Footer: Keyboard shortcuts
Keyboard Navigation
| Key | Action |
|---|---|
↑ / ↓ | Navigate menu items |
Enter | Activate selected item |
? | Open command palette |
Esc | Close palette / Cancel wizard |
Ctrl+Q | Quit dashboard |
Ctrl+C | Force exit |
All TUI components support standard terminal resize. The layout adapts to your terminal dimensions.
Command Palette
Press? to open the command palette:
- Type to filter commands
↑/↓to navigate resultsEnterto activateBackspaceto edit queryEscto close
Menu Sections
Entry Commands
Init
Launch the entry creation wizard. Guides you through all required fields, video configuration, credits, and download setup.
Update
Rehydrate an existing entry. Reads
entry.json, prompts for changes, and regenerates index.html.Doctor
Run health checks on all entries. Detects drift (JSON vs HTML differences) and offers safe auto-repair.
Entry Audit
Production-readiness audit. Validates schemas, asset references, download availability, and runtime requirements.
Content Commands
Catalog
Interactive catalog manager. Stage entries, edit manifest, set spotlight, diff against environments, and publish.
Home
Home featured entries manager. Configure homepage spotlights and featured entry carousels.
Notes
Dex Notes manager. Create and edit markdown blog posts with editorial workflow.
Polls
Polls catalog inspector. View in-repo polls data and submission tracking.
Calls
IN DEX calls registry. Manage submission calls, active states, and deadline tracking.
Newsletter
Newsletter manager. Draft campaigns, manage segments, schedule sends, and view stats.
Infrastructure Commands
Links
Open staff operational links in browser (monitoring dashboards, admin panels, etc.).
Assets
Protected assets manager. Validate and publish asset lookup configurations.
Status
Status incidents manager. Create incident pages, update status, and manage service health.
Deploy
Quick deploy shortcut. Runs preflight checks and pushes current branch to origin.
View
Launch localhost viewer. Opens generated entries in your browser at
http://localhost:4173.Init Wizard Flow
The Init wizard is the most complex TUI component:Wizard Stages
Basic Info
- Slug (auto-generated from title)
- Title
- Description
- Series (dex, inDex, dexFest)
- Selected buckets (A-E, X)
Credits
- Artists (comma-separated)
- Instruments (comma-separated)
- Video crew (director, cinematography, editing)
- Audio crew (recording, mix, master)
- Year, season, location
Credit Links
- Enable instrument links (optional)
- Add links per person
- Link validation (must be http/https)
Download Setup
- File specs (bit depth, sample rate, channels)
- Audio/video URLs per bucket and format
- Metadata (sample length, tags)
Recording Index
- PDF reference token (
lookup:orasset:) - Bundle reference token (
bundle:) - Google Sheets source URL
- Import from spreadsheet (Ctrl+I)
Wizard Keyboard Shortcuts
| Key | Action |
|---|---|
Enter | Advance to next field |
Tab | Next field (multi-field screens) |
Shift+Tab | Previous field |
Ctrl+N | Next section |
Ctrl+P | Previous section |
Ctrl+S | Save and generate |
Ctrl+I | Import recording index (on import screen) |
Esc | Cancel wizard |
Update Wizard Flow
The Update wizard rehydrates existing entries:- Select Entry: Choose from entries directory
- Load Data: Read
entry.jsonand populate forms - Edit Fields: Modify any section (preserves unchanged fields)
- Regenerate: Write updated
entry.jsonand regenerateindex.html
The Update wizard preserves the original
publishedAt timestamp and only updates updatedAt.Manager Components
Managers are full-screen TUI apps for content operations:Catalog Manager
A: Add entry to manifest (prompts for details)E: Edit selected entry metadataR: Retire selected entry (set status=archived)V: Run validation checksD: Diff local vs remote (prompts for env)P: Publish to environment (prompts for env and confirmation)
Home Manager
Similar to Catalog Manager but for homepage featured entries:Notes Manager
Markdown editor for Dex Notes:TUI Component Architecture
The TUI is built with React components via Ink:Key Components
Dashboard
ui/dashboard.mjs - Main dashboard container with menu and routing.Init Wizard
ui/init-wizard.mjs - Multi-stage entry creation wizard with form validation.Update Wizard
ui/update-wizard.mjs - Entry rehydration and edit workflow.Catalog Manager
ui/catalog-manager.mjs - Interactive catalog manifest editor.Logo Animation
The ASCII logo has animated HSV color cycling:Disable animations with
DEX_NO_ANIM=1 dex for better performance on slower terminals.Responsive Layout
The TUI adapts to terminal dimensions:- Width: 60 columns
- Height: 22 rows
Input Guard System
The TUI uses an input guard to sanitize keyboard input:Non-Interactive Mode
The TUI only launches when stdin/stdout are TTYs:- Dashboard doesn’t launch
- Falls back to non-interactive CLI mode
- Commands must specify all required flags
Best Practices
Keyboard First
The TUI is optimized for keyboard navigation. Memorize shortcuts for faster workflows.
Terminal Size
Use fullscreen terminal (min 80x24). Smaller sizes clip content and break layouts.
Disable Animations
Set
DEX_NO_ANIM=1 on slow terminals or during screen recording to reduce CPU usage.Review Before Save
Always review wizard screens before confirming. Canceling loses all progress.
Troubleshooting
Dashboard Won’t Launch
Ifdex doesn’t show the TUI:
- Check if stdin/stdout are TTYs:
tty - Verify terminal supports ANSI:
echo $TERM - Try explicit launch:
dex dashboard - Check for piping:
dex | catwill disable TUI
Layout Corruption
If the layout looks broken:- Resize terminal to at least 80x24
- Clear screen:
clearorCtrl+L - Restart dashboard:
Ctrl+Qthendex - Update terminal emulator (older versions have rendering bugs)
Keyboard Input Not Working
If keys don’t respond:- Check terminal raw mode:
stty -a | grep -i echo - Verify no conflicting keybindings in terminal emulator
- Try different terminal (iTerm2, Alacritty, etc.)
- Check Ink version:
npm list ink
Animation Lag
If logo animation is choppy:Animation lag usually indicates terminal emulator performance issues, not CLI problems.