vscli 0.1.8

A CLI tool to launch vscode projects, which supports devcontainers.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

# vscli

[![MIT License](https://img.shields.io/crates/l/vscli)](https://choosealicense.com/licenses/mit/) [![Continuous integration](https://github.com/michidk/vscli/workflows/Continuous%20Integration/badge.svg)](https://github.com/michidk/vscli/actions) [![Crates.io](https://img.shields.io/crates/v/vscli)](https://crates.io/crates/vscli) [![Homebrew](https://img.shields.io/badge/homebrew-available-blue?style=flat)](https://github.com/michidk/homebrew-tools/blob/main/Formula/vscli.rb) [![Chocolatey](https://img.shields.io/chocolatey/v/vscli?include_prereleases)](https://community.chocolatey.org/packages/vscli)

A CLI tool to launch vscode projects, which supports [devcontainer](https://containers.dev/).

![Screenshot showing the recent UI feature.](.github/images/recent.png)

## Features

- A shorthand for launching vscode projects (to be used like the `code` command but with devcontainer support)
- Detects whether a project is a [devcontainer](https://containers.dev/) project, and launches the devcontainer instead
- Supports the [insiders](https://code.visualstudio.com/insiders/) version of vscode
- Tracks your projects and allows you to open them using a CLI-based UI

## Installation

[![Packaging status](https://repology.org/badge/vertical-allrepos/vscli.svg)](https://repology.org/project/vscli/versions)

### [Cargo](https://doc.rust-lang.org/cargo/)

Install [vscli using cargo](https://crates.io/crates/vscli) on Windows or Linux:

```sh
cargo install vscli
```

### [Homebrew](https://brew.sh/)

Install [vscli using homebrew](https://github.com/michidk/homebrew-tools/blob/main/Formula/vscli.rb) on Linux:

```sh
brew install michidk/tools/vscli
```

### [Chocolatey](https://chocolatey.org/)

Install [vscli using Chocolatey](https://community.chocolatey.org/packages/vscli) on Windows:

```sh
choco install vscli
```

### Additional steps

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

```sh
alias vs="vscli --verbosity error"
alias vsr="vscli recent"
```

## Usage

### Commandline

After installation, the `vscli` command will be available:

```
Usage: vscli [OPTIONS] [PATH] [ARGS]... [COMMAND]

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

Arguments:
  [PATH]
          The path of the vscode project to open [default: .]

  [ARGS]...
          Additional arguments to pass to vscode

Options:
  -b, --behavior <BEHAVIOR>
          Launch behavior [default: detect]

          Possible values:
          - detect:          Use devcontainer if it was detected
          - force-container: Force open with devcontainer, even if no config was found
          - force-classic:   Ignore devcontainer

  -i, --insiders
          Whether to launch the insider's version of vscode

  -d, --dry-run
          Whether to launch in dry-run mode (not actually open vscode)

  -v, --verbosity <VERBOSITY>
          The verbosity of the output [default: info]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version
```

### Examples

#### Launching a project

You can launch a project using the default behavior:

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

The default behavior tries to detect whether the project is a [devcontainer](https://containers.dev/) project. If it is, it will launch the devcontainer instead - if not it will launch vscode normally.

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

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

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

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

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

```sh
vscli . -- --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:

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

Use the arrow keys to navigate the list, and press `enter` or `o` to open the selected project. Use `q` to quit the UI.
You can delete entries by highlighting them and pressing `x` or the `delete` key.