deco

dev container CLI for reading devcontainer configs

deco

deco is a Rust-first dev container CLI for reading devcontainer configs, preparing a local runtime, and running common devcontainer workflows from the terminal.

Who This Is For

Use deco if you want to:

• inspect a local .devcontainer/devcontainer.json
• build or start a devcontainer-oriented runtime
• run commands inside that runtime
• execute lifecycle hooks from the config
• inspect local features, templates, and lockfiles

Current Status

deco is being prepared for the current public alpha release: v1.0.0-alpha.4.

What is already covered:

• JSONC devcontainer parsing
• image, Dockerfile, and baseline compose config support
• read-configuration, build, up, exec, run-user-commands, set-up
• local features, templates, outdated, and upgrade flows
• machine-readable JSON output on stdout

What is still intentionally incomplete:

• full parity with upstream devcontainer-cli
• broad Docker runtime coverage in CI
• advanced publishing flows for features and templates

Install

From the repository root:

cargo install --path . --locked
deco --version
deco --help

Install the published Unix binary with:

curl -fsSL https://raw.githubusercontent.com/ilyar/deco/refs/heads/main/install.sh | bash

Pick a different directory or explicit tag if needed:

curl -fsSL https://raw.githubusercontent.com/ilyar/deco/refs/heads/main/install.sh | \
  bash -s -- --install-dir "$HOME/.local/bin" --version v1.0.0-alpha.4

Prebuilt binaries are published on GitHub Releases for:

• Linux x86_64
• Linux aarch64
• Windows x86_64
• macOS x86_64
• macOS aarch64
• FreeBSD x86_64

Download the asset that matches your platform from:

• https://github.com/ilyar/deco/releases/tag/v1.0.0-alpha.4

For local development without install:

cargo run -p deco -- --help

More detail: DEVELOP.md

Dev Container

The repository includes .devcontainer/devcontainer.json for a reproducible development environment with Rust, Docker tooling, GitHub CLI, and release-packaging dependencies preinstalled.

Use it if you want the same shell environment for development, validation, and Linux-side release preparation.

Development Commands

The primary local task runner is Justfile.

Common commands:

just ci
just build-release
just deco-read
just deco-build
just deco-up
just deco-exec pwd

Makefile remains as a compatibility wrapper, but new development and CI flow should use just.

Typical User Flow

Assume a workspace like this:

my-app/
  .devcontainer/
    devcontainer.json

Inspect the config

deco read-configuration --workspace-folder /path/to/my-app

Point to a specific file if needed:

deco read-configuration \
  --config /path/to/my-app/.devcontainer/devcontainer.json

Build the runtime

deco build --workspace-folder /path/to/my-app

Start the runtime

deco up --workspace-folder /path/to/my-app

Run a command inside the runtime

deco exec --workspace-folder /path/to/my-app -- pwd
deco exec --workspace-folder /path/to/my-app -- cargo test

If you already know the container id:

deco exec --container-id <container-id> -- env

Run lifecycle hooks from the config

deco run-user-commands --workspace-folder /path/to/my-app

Run the combined setup flow

deco set-up --workspace-folder /path/to/my-app

Command Examples

read-configuration

deco read-configuration --workspace-folder /path/to/my-app
deco read-configuration --workspace-folder /path/to/my-app --include-merged-configuration

build

deco build --workspace-folder /path/to/my-app

up

deco up --workspace-folder /path/to/my-app

exec

deco exec --workspace-folder /path/to/my-app -- pwd
deco exec --workspace-folder /path/to/my-app -- cargo check
deco exec --container-id abc123 -- ls -la

run-user-commands

deco run-user-commands --workspace-folder /path/to/my-app

set-up

deco set-up --workspace-folder /path/to/my-app

features

Inspect a local features directory:

deco features --manifest-dir /path/to/features

Resolve dependencies:

deco features resolve-dependencies --manifest-dir /path/to/features
deco features resolve-dependencies --workspace-folder /path/to/my-app

Run local manifest checks:

deco features test --manifest-dir /path/to/features

templates

Show template metadata from a local collection:

deco templates metadata --manifest-path /path/to/templates

Apply a template:

deco templates apply \
  --manifest-path /path/to/templates \
  --template-id alpha \
  --target-dir /tmp/template-output

outdated

deco outdated --workspace-folder /path/to/my-app
deco outdated --lockfile /path/to/deco-lock.json

upgrade

deco upgrade --workspace-folder /path/to/my-app --dry-run
deco upgrade --lockfile /path/to/deco-lock.json

Output Contract

deco writes machine-readable command results to stdout.

Diagnostics and logs go to stderr.

That means scripting should usually redirect stdout, for example:

deco read-configuration --workspace-folder /path/to/my-app > result.json

More detail: docs/stderr-convention.md

More Documentation

• DEVELOP.md for building, testing, releasing, and verifying artifacts
• CONTRIBUTING.md for contribution workflow and review expectations
• docs/installing.md for release downloads, install commands, and local release commands