vscli

A CLI/TUI which makes it easy to launch Visual Studio Code (vscode) projects, with a focus on dev containers.

Screenshot showing the recent UI feature.

Read here about the journey of reverse engineering Microsoft's dev container CLI in order to make this.

Features

A shorthand for launching vscode projects (to be used like the code command but with dev container support)
Detects whether a project is a dev container project, and launches the dev container instead
Supports multiple dev containers in the same project
Supports the insiders version of vscode
Tracks your projects and allows you to open them using a CLI-based UI

Installation

Cargo

Install vscli using cargo on Windows or Linux:

cargo install vscli

Homebrew

Install vscli using homebrew on Linux or Mac:

brew install michidk/tools/vscli

Chocolatey

Install vscli using Chocolatey on Windows:

choco install vscli

Winget

Install vscli using winget on Windows:

winget install vscli

Additional steps

You can set a shorthand alias for vscli in your shell's configuration file:

alias vs="vscli open"
alias vsr="vscli recent"

Usage

Commands

After installation, the vscli command will be available:

Usage: vscli [OPTIONS] <COMMAND>

Commands:
  open    Opens a dev container
  recent  Opens an interactive list of recently used workspaces
  help    Print this message or the help of the given subcommand(s)

Options:
  -s, --history-path <HISTORY_PATH>  Overwrite the default path to the history file [env: HISTORY_PATH=]
  -d, --dry-run                      Whether to launch in dry-run mode (not actually open vscode) [env: DRY_RUN=]
  -v, --verbose...                   More output per occurrence
  -q, --quiet...                     Less output per occurrence
  -h, --help                         Print help
  -V, --version                      Print version

Open Dev Containers

Opens a dev container.

Usage: vscli open [OPTIONS] [PATH] [ARGS]...

Arguments:
  [PATH]     The path of the vscode project to open [default: .]
  [ARGS]...  Additional arguments to pass to vscode [env: ARGS=]

Options:
  -b, --behavior <BEHAVIOR>          Launch behavior [default: detect] [possible values: detect, force-container, force-classic]
  -s, --history-path <HISTORY_PATH>  Overwrite the default path to the history file [env: HISTORY_PATH=]
  -c, --config <CONFIG>              Overwrites the path to the dev container config file [env: CONFIG=]
  -d, --dry-run                      Whether to launch in dry-run mode (not actually open vscode) [env: DRY_RUN=]
  -n, --insiders                     Whether to launch the insider's version of vscode [env: INSIDERS=]
  -v, --verbose...                   More output per occurrence
  -q, --quiet...                     Less output per occurrence
  -h, --help                         Print help (see more with '--help')

Recent UI

Opens an interactive list of recently used workspaces.

Usage: vscli recent [OPTIONS]

Options:
  -s, --history-path <HISTORY_PATH>  Overwrite the default path to the history file [env: HISTORY_PATH=]
  -d, --dry-run                      Whether to launch in dry-run mode (not actually open vscode) [env: DRY_RUN=]
  -v, --verbose...                   More output per occurrence
  -q, --quiet...                     Less output per occurrence
  -h, --help                         Print help

The following keybindings are available:

Keybindings

Key/Key Combination	Action	Description
`Esc`, `Ctrl+Q` or `Ctrl+C`	Quit	Exits the application.
`Down` or `Ctrl+J`	Select Next	Moves to the next selectable item.
`Up` or `Ctrl+K`	Select Previous	Moves to the previous selectable item.
`KeypadBegin` or `Ctrl+1`	Select First	Selects the first item.
`End` or `Ctrl+0`	Select Last	Selects the last item.
`Enter` or `Ctrl+O`	Open Selected	Opens the currently selected item.
`Delete`, `Ctrl+R`, or `Ctrl+X`	Delete Selected Entry	Deletes the currently selected item.

Note: If an input does not match any of the defined keybindings, it is treated as part of a search input.

Launch Behavior

There are three launch behaviors:

force-classic: Launch vscode without a dev container
force-container: Launch vscode with a dev container, error if no dev container is found
detect: Detect whether the project is a dev container project, and launch the dev container if it is

Detection Algorithm

The detection algorithm determines which dev container config to launch.

First, check whether a dev container config was specified via the --config flag -> launch it
Then loads the first dev container it finds
- If more than one exists -> show a interactive list of dev containers and let the user select one
- If one exists -> launch it
- If none exists -> launch vscode normally without a dev container

Examples

Launching a project

You can launch a project using the default behavior:

vscli open                          # open vscode in the current directory
vscli open .                        # open vscode in the current directory
vscli open /path/to/project         # open vscode in the specified directory

The default behavior tries to detect whether the project is a dev container project. If it is, it will launch the dev container instead - if not it will launch vscode normally.

You can change the launch behavior using the --behavior flag:

vscli open --behavior force-container .  # force open vscode dev container (even if vscli did not detect a dev container)
vscli open --behavior force-classic .    # force open vscode without a dev container (even if vscli did detect a dev container)

When you open a project containing more than one dev container config, you will be prompted to select one: Screenshot showing the dev container selection UI.

You can launch the insiders version of vscode using the --insiders flag:

vscli open --insiders .              # open vscode insiders in the current directory

Additional arguments can be passed to the code executable, by specifying them after --:

vscli open . -- --disable-gpu        # open vscode in the current directory without GPU hardware acceleration

Read more about the code flags, by executing code --help.

CLI UI

You can open a CLI-based user interface to display a list of recently opened projects using the recent command:

vscli recent                        # open the CLI-based UI to select a recently opened project to open

michidk / vscli

readme