CLI vs TUI Modes
Relevant source files
The following files were used as context for generating this wiki page:
vscli provides two primary modes of operation: a direct Command Line Interface (CLI) mode and an interactive Terminal User Interface (TUI) mode. The CLI mode is designed for immediate execution by passing specific paths and launch configurations, while the TUI mode (invoked via the recent command) provides an interactive environment for browsing, filtering, and launching recently opened workspaces.
Both modes share a common underlying architecture for workspace detection, history tracking, and editor orchestration, ensuring consistent behavior whether the user is launching from a shell script or an interactive session.
Architecture and Command Dispatch
The application uses clap to parse command-line options and determine which mode to enter. The entry point in main.rs dispatches logic based on the Commands enum.
Sources: src/main.rs:43-115, src/opts.rs:48-75
Command Comparison
The following table highlights the differences in configuration and intent between the two modes:
| Feature | CLI Mode (open) | TUI Mode (recent) |
|---|---|---|
| Primary Input | Explicit file path | Interactive selection from history |
| Interaction | Non-interactive (mostly) | Keyboard/Mouse driven TUI |
| Use Case | Shell aliases, scripts, direct folder opening | Resuming work on previous projects |
| Search/Filter | N/A | Fuzzy matching via nucleo-matcher |
| Customization | Specific CLI flags | UI toggles (--hide-info, etc.) |
Sources: src/opts.rs:48-75, README.md:103-149
CLI Mode: Direct Launch Logic
In CLI mode, the user specifies a path (defaulting to current directory). The system immediately attempts to resolve this path into a Workspace and determine the appropriate Behavior.
Launch Behavior Resolution
The CLI mode relies on three strategies defined in launch.rs:
- Detect: Searches for
.devcontainer.jsonor.devcontainer/devcontainer.json. If multiple are found, it may prompt the user even in CLI mode. - ForceContainer: Attempts to launch in a container; fails if no config is found.
- ForceClassic: Ignores any container configuration and opens the host path directly.
Sources: src/launch.rs:21-42, src/workspace.rs:125-149
Variable Substitution
When a dev container is detected, vscli parses the JSON config and performs variable substitution for container paths, supporting tokens like ${localWorkspaceFolder} and ${localWorkspaceFolderBasename}.
Sources: src/workspace.rs:77-94
TUI Mode: Interactive History Management
The TUI mode is implemented in src/ui.rs using the ratatui library. It transforms the historical data stored in history.json into a searchable, navigable table.
TUI Component Architecture
The TUI maintains a stateful UI struct that manages terminal frames, search input via tui-textarea, and table selection state.
Sources: src/ui.rs:142-160, src/ui.rs:88-106
Interactive Features
- Fuzzy Search: Uses
nucleo-matcherto calculate search scores across workspace names, container names, and paths. - Navigation: Supports standard keyboard shortcuts (Arrows, Ctrl+J/K) and mouse interactions (scrolling, clicking).
- Entry Management: Allows users to delete history entries directly from the UI using
DeleteorCtrl+X.
Sources: src/ui.rs:365-410, README.md:151-163
Shared Launch Logic
Regardless of the mode, once a workspace and behavior are finalized, the Setup::launch method handles the editor execution.
Environment Detection
vscli identifies if it is running within WSL (Windows Subsystem for Linux). If so, it uses wslpath2 to convert Linux-style paths to Windows-compliant paths before passing them to the editor URI, as editors like VS Code expect Windows paths when handling host-to-container mapping from WSL.
Sources: src/workspace.rs:194-219
Configuration and History
vscli persists state in a local history file. Both modes interact with this tracker to ensure the list of "Recent Workspaces" remains current.
| Option | Type | Description |
|---|---|---|
history_path | PathBuf | Path to history.json. Defaults to local data dir. |
dry_run | bool | If true, logs the command instead of executing it. |
behavior | Enum | detect, force-container, or force-classic. |
command | String | Editor binary (e.g., code, cursor, code-insiders). |
Sources: src/opts.rs:19-46, src/main.rs:55-65
History Lifecycle
- Load:
Tracker::loadreads the JSON file into aHistorymap. - Upsert: After a successful launch in either mode, a new
Entryis created or an existing one is updated with the latestlast_openedtimestamp. - Prune:
Tracker::storelimits the history toMAX_HISTORY_ENTRIES(currently 35) to keep the TUI performant. - Save: The final state is written back to disk upon application exit.
Sources: src/history.rs:24-38, src/history.rs:188-204, src/main.rs:120
Conclusion
The distinction between CLI and TUI modes in vscli allows it to serve as both a drop-in replacement for the code command and a robust project manager. The CLI mode focuses on speed and scriptability, while the TUI mode leverages historical data and interactive filtering to streamline the development workflow across multiple dev container environments.