devcontainer-cli

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:

OS=linux # also darwin
ARCH=amd64 # also 386
wget https://raw.githubusercontent.com/stuartleeks/devcontainer-cli/master/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:

. <(devcontainer completion bash)

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

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"]
}

TODO: Add docs on the folder structure for adding custom templates

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