devcontainer-sh

Zsh plugin for the devcontainer CLI — one dispatcher command, workspace auto-detection, and tab completion. Stop typing --workspace-folder.

CI Release Shell: zsh License: MIT

The upstream @devcontainers/cli is powerful but verbose — nearly every invocation needs --workspace-folder, there's no first-class "shell into the container" verb, and rebuild-and-recreate is a stack of flags. This plugin smooths those edges without hiding the underlying CLI: unknown flags pass straight through.

git clone https://github.com/devcontainer-env/devcontainer-sh \
 "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/devcontainer-sh"

Then add devcontainer-sh to the plugins=(...) line in your .zshrc.

zinit light devcontainer-env/devcontainer-sh

Add to your .zsh_plugins.txt:

devcontainer-env/devcontainer-sh

git clone https://github.com/devcontainer-env/devcontainer-sh ~/.zsh/devcontainer-sh
echo 'source ~/.zsh/devcontainer-sh/devcontainer-sh.plugin.zsh' >> ~/.zshrc

• zsh 5.0+
• @devcontainers/cli on $PATH (npm i -g @devcontainers/cli)
• Docker (for the down subcommand)

Usage: devcontainer-sh <subcommand> [args...]
Subcommands:
 up Create and start the dev container for this workspace
 shell, sh Open an interactive shell inside the container
 exec Run a one-off command in the container
 build Build the dev container image
 down Stop and remove the container associated with this workspace
 help Show usage
 version Plugin version + upstream CLI version

devcontainer-sh up — Create and start the dev container. Auto-detects --workspace-folder by walking up from $PWD to find .devcontainer/devcontainer.json or .devcontainer.json.

devcontainer-sh up -R # rebuild and recreate (-r remove + -n no-cache)
devcontainer-sh up -s # skip post-create commands

Shortcut flags: -r → --remove-existing-container, -n → --build-no-cache, -R → both, -s → --skip-post-create.

devcontainer-sh shell — Open an interactive shell inside the running container. With no argument, picks the best available shell (zsh > bash > sh); pass a name to override.

devcontainer-sh shell # auto-pick
devcontainer-sh shell bash # force bash
devcontainer-sh sh fish # short form

devcontainer-sh exec — Run a one-off command in the container. Everything is forwarded to devcontainer exec.

devcontainer-sh exec -- bash -lc 'pnpm test'

devcontainer-sh build — Build the dev container image.

devcontainer-sh build -n # --no-cache
devcontainer-sh build -p linux/amd64 # --platform linux/amd64

devcontainer-sh down — Stop and remove the container associated with the current workspace. Resolves the same devcontainer.local_folder label the CLI infers from --workspace-folder, then runs docker rm -f.

devcontainer-sh down

All subcommands walk up from $PWD looking for .devcontainer/devcontainer.json or .devcontainer.json and pass that directory as --workspace-folder. Pass --workspace-folder yourself to override.

Unknown flags are forwarded to the upstream CLI untouched, so anything documented in devcontainer up --help / exec --help / build --help still works (--log-level, --remote-env, --mount, --id-label, ...).

The plugin ships _devcontainer-sh (dispatcher) and _devcontainer (upstream binary) completion files. Both are added to $fpath on load — make sure compinit has been called in your .zshrc (oh-my-zsh / zinit / antidote do this for you).

MIT — Copyright (c) 2026 devcontainer-env