The 'recent' Command
Relevant source files
The following files were used as context for generating this wiki page:
The recent command is a core feature of vscli that provides an interactive Terminal User Interface (TUI) for browsing and launching recently opened workspaces. It acts as a project manager, allowing users to quickly resume work in specific dev containers or classic VS Code environments without manually navigating to the project directory or remembering complex CLI arguments.
The command leverages a local history file to track workspace metadata, including the workspace name, dev container configuration, and the specific editor behavior (e.g., command used, arguments, and launch strategy). By default, it presents a list of recently used projects sorted by the last time they were opened.
Sources: src/opts.rs:69-84, src/main.rs:80-128, README.md:120-131
Architecture and Data Flow
The recent command integrates three primary subsystems: the CLI Argument Parser, the History Tracker, and the TUI Rendering Engine. When the command is invoked, the system loads the history from a JSON file, initializes the interactive UI, and waits for a user selection or management action (such as deletion).
Application Execution Flow
The following diagram illustrates the lifecycle of a recent command invocation, from startup to workspace launch.
The flow begins in main.rs, where the Tracker is initialized by loading the history file (defaulting to data_local_dir()/vscli/history.json). If a user selects an entry, any flags passed via the command line (like --command or --behavior) override the settings stored in the history entry before the editor is launched.
Sources: src/main.rs:43-131, src/history.rs:163-228, src/ui.rs:341-432
Interaction and User Interface
The UI is built using ratatui and crossterm. It features a searchable table of workspaces and a status area displaying keybindings and metadata.
Components of the TUI
- Search Bar: A
tui-textareacomponent that allows fuzzy filtering of the workspace list. - Recent Workspaces Table: Displays workspace name, dev container name, path, and last opened timestamp.
- Status/Info Area: Displays available keybindings and detailed information about the selected entry (Strategy, Command, Args, and Config Path).
| UI Element | Description | Implementation Detail |
|---|---|---|
TableData | Manages rows, filtering, and sorting logic. | Uses nucleo-matcher for fuzzy searching. |
UI State | Holds the search text, table selection state, and visibility toggles. | Defined in src/ui.rs:162-170. |
AppAction | Enumerates user-triggered events like Quit, OpenSelected, or DeleteSelectedEntry. | Defined in src/ui.rs:26-36. |
Sources: src/ui.rs:25-250, README.md:135-155
Keybindings and Controls
The interface supports both keyboard and mouse interactions for navigation and management.
| Interaction | Action |
|---|---|
Enter / Ctrl+O | Open the selected workspace. |
Esc / Ctrl+Q / Ctrl+C | Exit without opening. |
Up/Down / Ctrl+J/K | Navigate the list. |
Del / Ctrl+R / Ctrl+X | Delete the selected entry from history. |
Mouse Wheel | Scroll through the workspace list. |
Left Click | Select row; double-click to open. |
Sources: src/ui.rs:434-477, README.md:135-155
Data Models
The functionality of the recent command relies on the Entry and History structures. These models define how workspace metadata is persisted and managed.
The Entry struct implements custom equality (PartialEq) that ignores the last_opened timestamp. This allows the History::upsert method to detect if a workspace is already in the list and simply update its "last opened" time rather than creating a duplicate.
Sources: src/history.rs:21-68, src/history.rs:85-135, src/launch.rs:60-66
Launch Overrides and Options
While the recent command recalls previous settings, it allows for on-the-fly overrides via CLI flags. These are defined in the LaunchArgs struct.
| Flag | Description | Default |
|---|---|---|
--command | Overwrites the editor command (e.g., code-insiders). | Stored in History |
--behavior | Overwrites the launch strategy (detect, force-container, force-classic). | Stored in History |
--config | Overwrites the path to the dev container configuration. | Stored in History |
--hide-instructions | Toggles the visibility of the keybinding guide in the UI. | false |
--hide-info | Toggles visibility of strategy, command, and path details. | false |
Sources: src/opts.rs:37-65, src/main.rs:91-110
History Management
The Tracker handles the persistence of history data. It enforces a limit on the number of stored entries to keep the history file manageable.
- Storage Limit: The system retains a maximum of 35 entries.
- File Format: History is stored in a pretty-printed JSON format.
- Error Handling: If the history file is corrupted, the system renames the broken file to a backup (e.g.,
.history_0.json.bak) and initializes a fresh history rather than crashing.
Sources: src/history.rs:16-18, src/history.rs:170-227
Summary
The recent command provides a centralized management interface for vscli users. By combining a persistent history tracker with an interactive TUI, it streamlines the process of reopening complex dev container environments. It maintains technical flexibility by allowing stored project settings to be overridden at runtime through CLI arguments.
Sources: src/main.rs:80-131, README.md:120-131