Ink CLI UI Migration Status

This document tracks the migration of promptfoo CLI commands to the new Ink-based interactive terminal UI.

Overview

The Ink UI provides a rich, interactive terminal experience with features like:

• Keyboard navigation (vim-style: j/k, g/G, PageUp/PageDown)
• Real-time search/filtering
• Infinite scroll with lazy loading
• Color-coded status indicators
• Responsive terminal layouts

Interactive UI is opt-in. Users must explicitly enable it:

PROMPTFOO_ENABLE_INTERACTIVE_UI=true promptfoo list evals

Command Migration Status

Legend

• ✅ Complete - Ink UI implemented and working
• 🚧 In Progress - Currently being developed
• 📋 Planned - On roadmap for future PR
• ➖ Not Applicable - Command doesn't benefit from interactive UI

Core Commands

List Commands

Auxiliary Commands

Component Architecture

src/ui/
├── index.ts                    # Public exports
├── interactiveCheck.ts         # Opt-in detection logic
├── render.ts                   # Ink rendering utilities
│
├── list/                       # List browser component
│   ├── index.ts                # Module exports
│   ├── ListApp.tsx             # Main list component
│   └── listRunner.tsx          # Entry point with dynamic imports
│
└── init/                       # (Future) Init wizard components
    └── components/
        └── shared/
            └── TextInput.tsx   # Reusable text input component

Core Infrastructure

List UI Components

Environment Variables

PR Roadmap

Based on the PR split strategy:

Design Principles

1. Opt-In by Default

Interactive UI requires explicit opt-in to ensure predictable behavior in scripts and CI pipelines.

2. Dynamic Imports

All Ink/React code is dynamically imported to prevent bundle bloat when promptfoo is used as a library:

// Good - dynamic import
export async function runInkList(options) {
  const [React, { renderInteractive }, { ListApp }] = await Promise.all([
    import('react'),
    import('../render'),
    import('./ListApp'),
  ]);
  // ...
}

3. Graceful Fallback

Every interactive command has a non-interactive fallback (table output, plain text) for non-TTY environments.

4. Client-Side Filtering

Search and filter operations happen in-memory on loaded data for instant feedback without network latency.

5. Vim-Style Navigation

Consistent keyboard shortcuts across all interactive components:

• j/k or ↑/↓: Navigate
• g/G: Jump to start/end
• PageUp/PageDown: Page navigation
• /: Search
• Enter: Select
• q or Esc: Exit

Testing

# Enable interactive UI and test
PROMPTFOO_ENABLE_INTERACTIVE_UI=true npm run local -- list evals

# Run UI tests
npx vitest run test/ui

Future Considerations

1. Default Behavior: After stabilization, consider making Ink UI the default for TTY environments
2. Feature Flags: Individual commands could have their own enable/disable flags
3. Theming: Support for custom color schemes
4. Accessibility: Screen reader support via Ink's accessibility features