| name | devcontainer-cli |
| description | This skill should be used when the user asks about "devcontainer CLI", "devcontainer up", "devcontainer exec", "devcontainer build", "devcontainer read-configuration", "run-user-commands", "CI devcontainer", "install devcontainer CLI", or needs to automate devcontainer operations from the command line.
|
Dev Container CLI Reference
Overview
The devcontainer CLI (@devcontainers/cli) provides full container lifecycle management
through subcommands and flags. All commands support JSON output for programmatic integration.
Install via npm install -g @devcontainers/cli or manage through mise.
Core Commands
devcontainer up
Create and start a development container.
devcontainer up --workspace-folder .
devcontainer up --workspace-folder . --remove-existing-container
devcontainer up --workspace-folder . --config .devcontainer/custom.json
Key flags:
--workspace-folder <path> — Workspace directory (required)--config <path> — Custom devcontainer.json path--remove-existing-container — Delete and recreate--skip-post-create — Skip postCreateCommand and later--skip-non-blocking-commands — Stop after updateContentCommand--mount <spec> — Add mounts (repeatable)--remote-env <KEY=VALUE> — Add env vars (repeatable)--id-label <KEY=VALUE> — Container tracking labels--image-name <image> — Specify output image name
JSON output:
{"outcome": "success", "containerId": "<id>", "remoteUser": "<user>", "remoteWorkspaceFolder": "/path"}
devcontainer exec
Execute a command in a running container.
devcontainer exec --workspace-folder . -- npm test
devcontainer exec --workspace-folder . --remote-env CI=true -- pytest
Key flags:
--workspace-folder <path> — Target workspace--id-label <KEY=VALUE> — Target by label--remote-env <KEY=VALUE> — Add env vars for command- Arguments after
-- passed to target command
devcontainer build
Build container image from configuration.
devcontainer build --workspace-folder . --image-name ghcr.io/org/repo:tag
devcontainer build --workspace-folder . --image-name img --platform linux/amd64,linux/arm64 --push
Key flags:
--workspace-folder <path> — Source workspace (required)--image-name <image> — Output image reference (required)--no-cache — Skip layer caching--platform <platforms> — Multi-platform build--push — Push to registry after build--cache-from <image> — Pull build cache from registry
devcontainer run-user-commands
Re-execute lifecycle commands on a running container.
devcontainer run-user-commands --workspace-folder .
devcontainer run-user-commands --workspace-folder . --skip-non-blocking-commands
Use case: Re-run setup after config changes, debug lifecycle issues.
devcontainer read-configuration
Output merged configuration for debugging.
devcontainer read-configuration --workspace-folder . --include-merged-configuration
Use case: Debug config resolution, understand feature merging, validate overrides.
CI/CD Patterns
GitHub Actions
- uses: devcontainers/ci@v0.3
with:
imageName: ghcr.io/${{ github.repository }}/devcontainer
push: filter
refFilterForPush: refs/heads/main
Manual CI Build
devcontainer build --workspace-folder . \
--image-name ghcr.io/org/repo:$SHA \
--cache-from ghcr.io/org/repo:main \
--push
Running Tests in CI
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . -- npm test
Additional Resources
Reference Files
For complete flag reference and all 11 subcommands:
references/cli-full-reference.md — All subcommands, flags, and output formats
Related Skills
- devcontainer-lifecycle — Understanding lifecycle events the CLI manages
- devcontainer-features — Feature CLI subcommands (test, package, publish)
