devctl TUI Guide

The devctl TUI is an "always-on" dashboard for your dev environment. It's designed to let you start/stop, inspect logs, and understand pipeline progress without constantly switching between separate terminal commands.

Quick workflow: start, debug, restart

Here's the most common TUI workflow—starting your environment, finding a problem, and restarting:

1. Start the TUI              devctl tui
2. Press `u` to start         → Dashboard shows services spinning up
3. See a service fail?        → Press `j/k` to select it, `l` to see logs
4. Fix the issue              → In your editor
5. Press `Esc` to return      → Back to Dashboard
6. Press `r` on Dashboard     → Confirms, runs down + up
7. Or press `r` in Service    → Restarts only that service
8. Press `q` to quit          → When done for the day

The TUI remembers state between restarts—if you quit and come back, it'll show what's currently running.

1. Starting the TUI

The TUI is just another devctl command. It reads the same .devctl.yaml, applies .devctl.override.yaml when present, uses the same repo-root resolution rules, and will surface the same plugin/plan errors you’d see in the CLI.

devctl tui

Useful flags:

• --profile backend: run the TUI with a selected profile.
• --alt-screen (default true): use the terminal alternate screen buffer.
• --refresh 1s: state polling interval.
• --debug-logs: allow logs to stdout/stderr while the TUI runs (may corrupt the UI).

devctl tui --profile backend --alt-screen=false --refresh 1s

2. Global navigation and help

The TUI is organized into views. You can switch between views quickly and always pull up a help overlay that matches the current build of the UI.

Global keys:

• q or ctrl+c: quit
• ?: toggle help overlay
• tab: switch view (Dashboard → Events → Pipeline → Plugins → Dashboard)

3. Dashboard view: the “control panel”

The Dashboard view is where you’ll spend most of your time. It shows whether state exists, lists services, and offers the common actions: up, down, restart, kill, and open logs.

Dashboard keys:

• ↑/↓ or k/j: select a service
• enter or l: open the Service view (logs) for the selected service
• u: start the environment (or prompt to restart if state already exists)
• d: stop the environment (with confirmation)
• r: restart the environment (with confirmation)
• x: send SIGTERM to the selected service PID (with confirmation)

Practical workflow:

1. Press u to start.
2. If something fails, switch to Pipeline (tab) to see which phase errored.
3. Switch back to Dashboard to select a service and press l for logs.

4. Service view: logs, filtering, and follow mode

The Service view shows process information plus a scrollable log viewport. It can show stdout or stderr, and it supports simple filtering for “find the one error line”.

Service keys:

• tab: toggle stdout/stderr stream
• f: toggle follow mode (auto-refresh the viewport)
• /: set a filter string (press enter to apply)
• ctrl+l: clear the filter
• s: stop the selected service
• r: restart the selected service
• d: detach back to the Dashboard
• esc: also returns to the Dashboard

If you only need a quick tail or a service lifecycle action outside the TUI, remember the equivalent CLI commands:

devctl logs --service <name>
devctl logs --service <name> --stderr
devctl logs --service <name> --follow
devctl stop-service <name>
devctl restart <name>
devctl start <name>

Service-level restart re-runs config.mutate and launch.plan to recover the selected service specification, but it does not run build, prepare, or validate phases.

5. Events view: a live event log with filters

The Events view is the “what happened?” view. It aggregates system and per-service events and lets you filter aggressively when a noisy environment is drowning out the signal.

Core keys:

• /: set a text filter (press enter to apply)
• ctrl+l: clear the filter
• c: clear the event buffer

Advanced filtering keys:

• l: open the log-level filter menu
  • d/i/w/e: toggle debug/info/warn/error
  • a: enable all levels
  • n: disable all levels
  • esc/enter/l: close the menu
• p: pause/unpause event ingestion (useful during fast scroll); unpausing flushes a bounded queue
• space: toggle “system” events
• 1–9: toggle service filters by index (useful when you have a stable service list)

6. Pipeline view: understand what devctl is doing

The Pipeline view shows phases and results from the most recent up/restart. This is where you go to understand “why did up fail?” without digging through raw logs.

Pipeline keys:

• b: focus the Build section
• p: focus the Prepare section
• v: focus the Validation section
• ↑/↓ or k/j: move selection
• enter: toggle details for the selected item
• o: toggle the live output viewport (when available)

7. Plugins view: inspect configured plugins

The Plugins view is a quick inventory: it lists configured plugins and whether they are active/disabled/error, and allows expanding items for details.

Plugins keys:

• ↑/↓ or k/j: select a plugin
• enter or i: expand/collapse the selected plugin
• a: expand all
• A: collapse all
• esc: back

If you’re debugging protocol-level issues (handshake failures, invalid JSON), the CLI plugins list output is still the best raw signal:

devctl plugins list

8. Capturing output and debugging UI issues

The TUI is interactive, which makes “capture a bug report” slightly harder than with a plain CLI command. The trick is to run with settings that make capture deterministic.

8.1. Disable alt-screen for capture

Running with --alt-screen=false keeps the UI in the normal terminal buffer so your terminal (or tmux) can capture it.

devctl tui --alt-screen=false

8.2. Avoid debug logs unless you need them

--debug-logs allows logging to stdout/stderr while the UI is running. This is useful when debugging the UI itself, but it can corrupt rendering and make screenshots/captures misleading.

devctl tui --debug-logs

9. Where to go next

If you’re new to devctl overall, start with the user guide:

devctl help user-guide

If you want profile-specific TUI runs, read:

devctl help profiles-guide

If you want to extend devctl with real repo logic, move on to scripting and plugin authoring:

devctl help scripting-guide
devctl help plugin-authoring