Installation Guide
Relevant source files
The following files were used as context for generating this wiki page:
The vscli tool is a command-line utility and Terminal User Interface (TUI) designed to streamline the process of launching Visual Studio Code projects with dev container support. It serves as a wrapper for the code command, providing automated detection of dev container configurations and a history tracking system for recently accessed workspaces.
This guide covers the various methods available for installing vscli across different operating systems, including Windows, macOS, and Linux, as well as the initial configuration steps required to optimize the tool's utility in a development workflow.
Sources: README.md:1-12, src/main.rs:1-15
Supported Platforms and Package Managers
vscli is cross-platform and can be installed through several popular package managers. The project is built using the Rust programming language and utilizes a stable toolchain.
Installation Methods
| Platform | Package Manager | Command |
|---|---|---|
| Windows / Linux | Cargo | cargo install vscli |
| macOS / Linux | Homebrew | brew install michidk/tools/vscli |
| Windows | Chocolatey | choco install vscli |
| Windows | Winget | winget install vscli |
Sources: README.md:21-50, Cargo.toml:1-15, rust-toolchain.toml:1-4
System Dependencies and Requirements
The tool relies on several core libraries and external tools to function correctly. While many are bundled within the binary, the underlying editor must be present on the system path.
Editor Requirements
vscli does not bundle an editor; it invokes existing installations. Supported editors include:
- Visual Studio Code (
code) - Visual Studio Code Insiders (
code-insiders) - Cursor (
cursor) - VSCodium (
codium) - Positron (
positron)
Sources: README.md:145-155, src/launch.rs:88-98
Build Requirements (for Cargo Installation)
If installing via Cargo, the system must have the Rust stable toolchain installed. The project uses the 2024 edition of Rust.
Sources: Cargo.toml:4, rust-toolchain.toml:1-4
Initial Configuration
Once installed, vscli offers several configuration options via environment variables and shell aliases to improve the user experience.
Shell Aliases
It is highly recommended to set up aliases in your shell configuration file (e.g., .bashrc, .zshrc) to provide shorter access to the main commands.
# Recommended aliases for vscli
alias vs="vscli open"
alias vsr="vscli recent"
Sources: README.md:52-57
Environment Variables
The application supports configuration through environment variables, which can be overridden by CLI flags.
| Variable | Description | Related Flag |
|---|---|---|
HISTORY_PATH | Overwrites the default path to the history file. | --history-path |
DRY_RUN | Enables dry-run mode (does not actually open the editor). | --dry-run |
COMMAND | Sets the default editor command to use. | --command |
CONFIG | Overwrites the path to the dev container config file. | --config |
Sources: README.md:65-95, src/opts.rs:20-45
Post-Installation Architecture
The following diagram illustrates how vscli interacts with the system after installation to manage workspaces and launch the editor.
This diagram shows the flow from user input through the history tracking and detection logic to the final editor execution.
Sources: src/main.rs:43-113, src/workspace.rs:215-260
Verification
To verify that the installation was successful and the path is correctly configured, run the following command:
vscli --version
This should return the current version of the tool (e.g., vscli 1.3.0).
Sources: Cargo.toml:3, src/opts.rs:16
Summary
vscli provides a flexible installation process through major package managers like Cargo, Homebrew, Chocolatey, and Winget. By configuring shell aliases and environment variables, users can seamlessly integrate vscli into their existing development workflows, enabling faster access to dev container environments across multiple editors.