vscli

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

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:

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