Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
vscli is a command-line interface and terminal user interface (TUI) tool designed to streamline the process of launching Visual Studio Code projects, with a primary focus on Dev Containers. It acts as a wrapper for the code command (and other forks like Cursor or VSCodium), automatically detecting container configurations and managing a history of recently accessed workspaces.
Sources: README.md:1-10, src/main.rs:13-15
Installation and Setup
The project is built with Rust and can be installed via multiple package managers across Linux, Windows, and macOS.
| Method | Command | Platform |
|---|---|---|
| Cargo | cargo install vscli | Windows, Linux |
| Homebrew | brew install michidk/tools/vscli | Linux, macOS |
| Chocolatey | choco install vscli | Windows |
| Winget | winget install vscli | Windows |
Sources: README.md:23-56
Shell Aliases
For improved efficiency, it is recommended to set up aliases in your shell configuration (e.g., .bashrc or .zshrc):
alias vs="vscli open"
alias vsr="vscli recent"
Sources: README.md:58-63
Core Architecture and Execution Flow
When a user executes vscli, the application parses command-line options using clap and initializes a Tracker to manage the local history file. The execution then branches based on the subcommand: open or recent.
The following diagram illustrates the high-level logic flow when launching a project:
Sources: src/main.rs:32-111, src/opts.rs:13-33
Workspace Launching Logic
The primary function of vscli is to determine the appropriate ContainerStrategy and execute the editor command with the correct URI.
Launch Strategies
The tool supports three distinct behaviors for handling Dev Containers:
| Strategy | Description |
|---|---|
detect | (Default) Checks for .devcontainer.json or .devcontainer/devcontainer.json. Launches container if found, otherwise opens on host. |
force-container | Attempts to launch in a container; errors if no configuration is found. |
force-classic | Ignores any container configurations and opens the project on the host system. |
Sources: src/launch.rs:18-42, README.md:144-151
Detection Algorithm
The Workspace module searches for configurations in specific locations:
.devcontainer.jsonin the workspace root..devcontainer/devcontainer.json.- Any
devcontainer.jsonone level deep inside the.devcontainer/directory.
If multiple configurations are found, the tool uses inquire::Select to prompt the user for a choice.
Sources: src/workspace.rs:118-146, src/launch.rs:114-135
Interactive TUI (Recent Workspaces)
The recent command launches a TUI built with ratatui that allows users to browse and search through their workspace history.
Sequence of TUI Selection and Launch
Sources: src/ui.rs:245-314, src/main.rs:77-105
Keybindings for the TUI
| Key | Action |
|---|---|
Up / Down | Navigate through recent entries |
Enter | Open selected workspace |
Del / Ctrl+X | Remove entry from history |
Esc / Ctrl+C | Quit UI |
Character Keys | Input search filter (Fuzzy Matching) |
Sources: src/ui.rs:356-384, README.md:118-131
History Management
History is persisted in a JSON file, typically located in the user's local data directory (e.g., ~/.local/share/vscli/history.json).
- Entry Structure: Stores the workspace name, container name, filesystem path, config path, and the last used launch behavior.
- Persistence: The
Trackerensures only the most recent 35 entries are kept. - Deduplication: Entries are compared based on path and behavior to prevent duplicate rows when the same project is opened repeatedly.
Sources: src/history.rs:14-41, src/history.rs:188-195, src/main.rs:43-52
Summary
vscli simplifies the overhead of managing Dev Container-enabled projects. By integrating a detection algorithm with a persistent history tracker and an interactive TUI, it provides a unified interface for various VS Code-based editors across different operating systems, including support for WSL environments.
Sources: README.md:1-15, src/workspace.rs:175-212