The 'open' Command
Relevant source files
The following files were used as context for generating this wiki page:
The open command is the primary entry point for vscli to launch Visual Studio Code projects. It is designed to act as a wrapper for the code command (or other compatible editors like Cursor), providing automated detection and configuration for dev containers. When executed, the command analyzes a target directory, identifies potential dev container configurations, and launches the editor with the appropriate remote URI or local path based on the user's specified behavior.
Beyond simply launching the editor, the open command integrates with the project's history system. Every successful execution updates a local history file, tracking the workspace path, used dev container, and launch configurations. This metadata enables features like the Recent UI and ensures consistent launch behaviors across sessions.
Sources: src/main.rs:48-77, README.md:104-122
Command Architecture and Execution Flow
The open command follows a structured execution pipeline: it parses CLI arguments, initializes a workspace representation, determines the dev container strategy, and finally executes the editor process.
The logic flow ensures that even if dev container detection is requested, the system can gracefully fall back to a "classic" host-based launch if no configuration is found, unless explicitly forced otherwise.
Sources: src/launch.rs:136-184, src/main.rs:48-77
Input Parameters and Configuration
The open command accepts a path and several optional flags to control the editor choice and dev container behavior.
| Argument/Option | Type | Default | Description |
|---|---|---|---|
PATH | Positional | . | The filesystem path of the vscode project to open. |
--command, -c | String | code | The editor executable to use (e.g., code-insiders, cursor). |
--behavior, -b | Enum | detect | Defines how dev containers are handled (detect, force-container, force-classic). |
--config | Path | None | Explicitly defines the path to a devcontainer.json file. |
--args | Vec | [] | Additional arguments passed directly to the editor executable. |
--dry-run, -d | Boolean | false | If true, logs the command instead of executing it. |
Sources: src/opts.rs:39-65, README.md:104-122
Launch Strategies
The ContainerStrategy enum determines the logic applied during the launch phase:
- Detect: Searches for dev container configurations. If one or more are found, it prompts for selection or uses the single match. If none are found, it opens the path locally.
- ForceContainer: Same as detect, but results in an error if no dev container configuration is discovered.
- ForceClassic: Completely ignores any dev container configurations and opens the local folder on the host system.
Sources: src/launch.rs:18-47, src/launch.rs:141-182
Dev Container Detection Logic
When the strategy requires detection, vscli scans the workspace for configuration files. It mimics the standard VS Code detection algorithm by checking specific locations relative to the workspace root.
- Direct Check: Looks for
.devcontainer.jsonin the root. - Folder Check: Looks for
.devcontainer/devcontainer.json. - Subfolder Check: Searches one level deep inside the
.devcontainer/directory (e.g.,.devcontainer/web-app/devcontainer.json).
If multiple configurations are found, vscli utilizes the inquire crate to present an interactive selection prompt to the user.
Sources: src/workspace.rs:138-171, src/launch.rs:114-134
Editor Execution and URI Generation
Launching a dev container requires converting the local path and configuration path into a specialized vscode-remote URI. This URI is Hex-encoded and passed to the editor via the --folder-uri argument.
URI Structure
The URI is constructed using the following components:
- Scheme:
vscode-remote://dev-container+ - Hex Segment: A JSON-serialized object containing the
hostPathand theconfigFileURI. - Path: The path to the workspace folder inside the container (defaults to
/workspaces/{name}).
let folder_uri = DevcontainerUriJson {
host_path: ws_path,
config_file: FileUriJson::new(dc_path.as_str()),
};
let json = serde_json::to_string(&folder_uri)?;
let hex = hex::encode(json.as_bytes());
let uri = format!("vscode-remote://dev-container+{hex}{container_folder}");
Sources: src/workspace.rs:240-250, src/uri.rs:37-46
Environment Support (WSL)
On Linux/Unix systems, the command detects if it is running inside WSL (Windows Subsystem for Linux). If detected, it uses wslpath2 to convert WSL-style paths to Windows-style paths before URI generation, ensuring the Windows host-side editor can resolve the files.
Sources: src/workspace.rs:200-234
History Integration
Upon a successful launch, the command records the session in the history tracker. This allows the application to remember which dev container was used for a specific workspace and which editor was preferred.
Key fields stored in a history Entry:
workspace_name: Derived from the folder name.workspace_path: Canonicalized absolute path.config_path: Path to the selecteddevcontainer.json.behavior: The strategy, command, and extra arguments used.last_opened: UTC timestamp of the launch.
Sources: src/history.rs:22-33, src/main.rs:66-75
Summary
The open command transforms the manual process of opening dev containers into a single-step CLI operation. By automating workspace detection, path translation (especially for WSL), and URI encoding, it provides a seamless bridge between the terminal and VS Code's remote development features, while maintaining a persistent record of user activity for future sessions.