Home

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/main.rs
• src/workspace.rs
• src/launch.rs
• src/history.rs
• src/ui.rs
• src/opts.rs
• src/uri.rs

vscli is a command-line interface (CLI) and terminal user interface (TUI) tool designed to simplify the process of launching Visual Studio Code (and compatible editors like Cursor) projects, with a specific focus on dev containers. It automates the detection of dev container configurations and provides an interactive way to manage and reopen recently used workspaces.

Sources: README.md:1-12, src/main.rs:1-10

The tool bridges the gap between the standard code command and the complex URI requirements needed to launch dev containers from outside the editor. It tracks project history to allow users to quickly resume work in specific environments without navigating the file system.

Sources: README.md:14-22, src/history.rs:165-175

Core Architecture

The architecture of vscli is built around a command-driven workflow that interacts with a history tracking system and a workspace detection engine.

Command Execution Flow

When a user executes a command, the application parses global options and subcommands to determine whether to open a specific path or launch the interactive TUI.

This diagram shows the high-level logic flow from initial command parsing to editor execution.
Sources: src/main.rs:37-108, src/opts.rs:45-78

Key Components

Component	Description	File
Tracker	Manages loading and storing the history.json file.	src/history.rs:165
Workspace	Handles filesystem logic for project paths and container config discovery.	src/workspace.rs:98
Setup	Orchestrates the launch strategy (Detect, Force Classic, or Force Container).	src/launch.rs:89
UI	Implements the Ratatui-based TUI for browsing recent entries.	src/ui.rs:155

Workspace & Dev Container Detection

The Workspace module is responsible for identifying valid projects and locating .devcontainer.json or equivalent files.

Detection Logic

The system searches for configurations in three specific locations, mirroring the behavior of Visual Studio Code:

1. A .devcontainer.json file in the root of the workspace.
2. A .devcontainer/devcontainer.json file.
3. Any devcontainer.json file located exactly one level deep within the .devcontainer/ directory (e.g., .devcontainer/web-stack/devcontainer.json).

Sources: src/workspace.rs:136-170

Launch Strategies

The Setup component applies a ContainerStrategy to determine how the editor should be opened:

Strategy	Behavior
Detect	Default. Opens in a container if a config is found; otherwise, opens normally.
ForceContainer	Attempts to open in a container; fails if no config is detected.
ForceClassic	Opens the workspace on the host system, ignoring any container configs.

Sources: src/launch.rs:24-41, src/launch.rs:125-168

History Management

vscli maintains a local history of recently opened projects to enable the "recent" TUI feature.

History Data Structure

History is stored as a JSON array of Entry objects. To keep the history performant, it is limited to a maximum of 35 entries.

The relationship between a history entry and its associated launch behavior.
Sources: src/history.rs:19-35, src/launch.rs:62-68

Persistence

The history file is typically located in the local data directory (e.g., ~/.local/share/vscli/history.json). If a history file becomes corrupted, the application creates a backup (e.g., .history_0.json.bak) and starts a fresh history.
Sources: src/main.rs:55-65, src/history.rs:199-231

Execution Engine

Launching the editor involves constructing complex URIs, especially for dev containers which require a Base64-encoded (hex-encoded in implementation) JSON blob representing the vscode-remote target.

Remote URI Construction

For dev containers, vscli generates a URI following this pattern:
vscode-remote://dev-container+<HEX_ENCODED_JSON><CONTAINER_FOLDER>

The sequence of transforming local paths into a remote-compatible URI for the editor.
Sources: src/workspace.rs:244-256, src/uri.rs:11-44

Platform Support

The execution engine handles OS-specific logic:

• Windows: Executes via cmd /c to ensure editor commands in the PATH are found correctly.
• WSL: Detects if it is running inside Windows Subsystem for Linux and converts paths using wslpath2 before constructing the remote URI.
• Unix: Directly executes the command.

Sources: src/workspace.rs:198-238, src/workspace.rs:288-316

Summary

vscli serves as a specialized launcher that automates the discovery and configuration of dev container environments. By combining a robust detection algorithm, history tracking, and a cross-platform execution engine, it provides a streamlined workflow for developers using containerized development environments across different operating systems and editors.