devcontainer-cli

devcontainer-cli is the start of a CLI to improve the experience of working with Visual Studio Code devcontainers

Status: this is a pet project that I've been experimenting with. It is not supported and you should expect bugs :-)

Installation

Head to the latest release page and download the archive for your platform.

Extract devcontainer from the archive and place in a folder in your PATH.

Or if you just don't care and are happy to run random scripts from the internet:

export OS=linux # also darwin
export ARCH=amd64 # also 386
wget https://raw.githubusercontent.com/stuartleeks/devcontainer-cli/main/scripts/install.sh
chmod +x install.sh
sudo -E ./install.sh

Enabling bash completion

To enable bash completion, add the following to you ~/.bashrc file:

source <(devcontainer completion bash)

Or to alias devcontainer (to dc in this example):

alias dc=devcontainer
complete -F __start_devcontainer dc

Usage

Working with devcontainers

Listing devcontainers

To see which running devcontainers the CLI detects you can run the list command.

Running commands inside a devcontainer

devcontainer allows you to run commands in devcontainers. This is similar to docker exec but works with devcontainer names (rather than requiring container names/IDs).

For example:

# Run an interactive bash shell in the vscode-remote-test-dockerfile devcontainer
devcontainer exec vscode-remote-test-dockerfile bash

# Run a command with args in the vscode-remote-test-dockercompose_devcontainer/mongo devcontainer
devcontainer exec vscode-remote-test-dockercompose_devcontainer/mongo ls -a /workspaces/vscode-remote-test-dockerfile

You can pass ? as the devcontainer name and the CLI will prompt you to pick a devcontainer to run the exec command against, e.g.:

$ ./devcontainer exec ? bash
Specify the devcontainer to use:
   0: devcontainer-cli (festive_saha)
   1: vscode-remote-test-dockerfile (fervent_gopher)
0

You can use this with Windows Terminal profiles:

{
    "guid": "{4b304185-99d2-493c-940c-ae74e0f14bba}",
    "hidden": false,
    "name": "devcontainer exec",
    "commandline": "wsl bash -c \"path/to/devcontainer exec ? bash\"",
},

Working with devcontainer templates

To work with devcontainer templates devcontainer needs to know where you have the templates stored.

As a quickstart, clone the VS Code devcontainers repo: git clone https://github.com/microsoft/vscode-dev-containers

Next, run devcontainer config write to save a config file and then open ~/.devcontainer-cli/devcontainer-cli.json in your favourite editor.

The starting configuration will look something like:

{
  "templatepaths": []
}

Update to include the path to the containers folder in the vscode-dev-containers repo you just cloned:

{
  "templatepaths": ["$HOME/source/vscode-dev-containers/containers"]
}

See Template Paths for more details of the structure of template folders.

Listing templates

Running devcontainer template list will show the templates that devcontainer discovered

Adding a devcontainer

To add the files for a devcontainer definition to your project, change directory to the folder you want to add the devcontainer to and then run:

# Add the go template
devcontainer template add go

This will copy in the template files for you to modify as you wish.

Adding a link to a devcontainer

If you are working with a codebase that you don't want to commit the devcontainer definition to (e.g. an OSS project that doesn't want a devcontainer definition), you can use the template add-link command. Instead of copying template files it creates symlinks to the template files and adds a .gitignore file to avoid accidental git commits.

As with template add, run this from the folder you want to add the devcontainer to:

# Symlink to the go template
devcontainer template add-link go

Template paths

devcontainer can be configured to scan multiple folders to find templates. It is designed to work with folders structured in the same was as the containers from in github.com/microsoft/vscode-dev-containers.

Assuming you cloned github.com/microsoft/vscode-dev-containers/ into your ~/source/ folder and set up a custom devcontainer folder in ~/source/devcontainers then you can configure your template paths as shown below. The sub-folder names are used as the template name and when duplicates are found the first matching folder is taken, so in the example below the ~/source/devcontainers templates take precedence.

{
  "templatepaths": [
    "$HOME/source/devcontainers",
    "$HOME/source/vscode-dev-containers/containers"
  ]
}

The structure for these template paths is shown in the following tree structure:

template-collection-folder
 |-template1
 |  |-.devcontainer
 |  |  |-devcontainer.json
 |  |  |-Dockerfile
 |  |  |-<other content for the template>
 |-misc-folder
 |-<misc content that is ignored as there is no .devcontainer folder>
 |-<README or other files that are ignore>

lawrencegripper / devcontainer-cli