devcontainer-cli-global

name	devcontainer-cli-global
description	Host-global official @devcontainers/cli helpers. ALWAYS dc-exec — NEVER raw docker exec NAME (DC app = official CLI; compose-kind = docker compose exec inside dc-exec). Engine wall: dc-recover --yes (existing Desktop/Colima/dockerd). Disk full: dc-df then dc-prune --yes. Port clash: --take-ports stops labeled foreign or proven compose-kind working_dir; unlabeled report-only. dc-forward needs one app or --id (not auto on compose-kind). dc-db on a declared port. dc-files yazi/nnn or Linux yazi in /tmp. dc-doctor read-only. NEVER docker system prune -af --volumes. Install: curl main/install.sh | bash -s -- --with-cli (or brew tap Brasth/dc-cli). No project .devcontainer edits.
version	34
created	2026-08-13
updated	2026-08-27

When to Use

First minute: dc doctor (read-only). Host wall on an existing engine → dc-recover then dc-recover --yes. This folder: .devcontainer or compose → dc-up; else dc-try --yes (never edit the project). Then dc-exec. Never raw docker exec NAME.

Procedure

1. Confirm Docker/Colima (read-only dc-doctor or docker ps). dc-doctor never mutates. Host wall on an existing engine: dc-recover (print) then dc-recover --yes (start Desktop/Colima/dockerd, pick-one + stop extra, context, Linux group). TUI blocked board [f] is the same apply. Empty machine: do not install; point at Desktop guide / Colima brew copy. On Docker Desktop, run dc-doctor before dc-up — docker_context must be one live engine (CLI socket). Linux Desktop is ~/.docker/desktop/docker.sock (engine=desktop), not unknown. Split-brain is a blocker; dc-recover --yes stops the extra after context use. dc-engine --fix still prints; --yes is context only. DC_UP_ALLOW_SPLIT=1 is a last-resort hatch only. This folder is kind=devcontainer if project config exists (official CLI required), else kind=compose if a root compose file exists (official CLI not required), else kind=none (use dc-try for a sandbox; dc-up on a TTY offers that sandbox, non-TTY prints the dc-try hint). Still stuck after apply: dc-recover --report (no secrets).
2. Never edit project .devcontainer/devcontainer.json.
3. Interactive: dc-tui (current folder; Go/release/brew click-board) or dc-tui --all (fleet). Logo splash first (any key skips; DC_TUI_NO_SPLASH=1). Primary: start/shell/stop. Meta: open/attach/ports/logs/top/nets/db/files. Published websites become clickable http://127.0.0.1:PORT tiles (1–9). Databases stay off that row — b / dc-db opens TablePlus on a declared compose/forwardPorts host port (never invents; two DBs need --service). m / dc-files leave-execs yazi/nnn if already in the image, else copies a Linux yazi into /tmp (never apt-get). e / dc-exec is a color shell (hl highlights access logs). l follows highlighted docker logs for the selected stack row (q back). R restarts that sibling via dc-exec --service NAME --restart (labeled app row refuses — u/s; r still reloads). t is live CPU/RAM for this folder via dc-stats (q back). n lists this folder's declared compose nets; y creates missing external: true bridge nets then dc-up --create-nets. Fleet refuses t, n, l, and R. rm asks y/n. j/k + enter on rows. Header shows compact disk (dc-df) and an app load pulse (dc-stats). Key d = full dc-df. After shell/files the board resumes. open = host editor; attach = VS Code Remote. ports = sidecar. Install: curl -fsSL https://raw.githubusercontent.com/Brasth/dc-cli/main/install.sh | bash -s -- --with-cli (standalone CLI) or brew tap Brasth/dc-cli && brew install dc-cli. Diagnose with read-only dc-doctor before destructive recovery.
4. Start: kind=devcontainer → dc-up (official CLI) then auto dc-forward. kind=compose → dc-up is docker compose -p NAME -f FILES up -d (no official CLI, no auto dc-forward). kind=none → dc-try (external override under $XDG_STATE_HOME/dc-cli/try/; never edits the project; default localhost forwardPorts + dc-forward; no hooks). TUI start on none confirms then dc-try --yes. TTY dc-up offers dc-try; agents use dc-try --yes; dc-recover --yes may apply try_sandbox. Non-TTY / --yes on dc-up refuse with a dc-try hint. Only dc-up --ports if user accepts REPLACE (devcontainer only). On ENOSPC, dc-up prints dc-df / dc-prune hints. Missing declared external nets: TTY prompt, or dc-up --create-nets / --yes / DC_UP_CREATE_NETS=1. --create-nets does not take ports. Overlay / custom IPAM / inspect-unknown = refuse. On port already allocated, dc-up lists the holder; on a TTY it asks to stop and retry; agents use dc-up --take-ports / --yes. Stops positively labeled foreign stacks/sidecars or a compose-kind folder whose working_dir/config_files prove ownership. Unlabeled, name-only, ambiguous, or inspect-unknown stay report-only. Do not invent docker system prune.
5. Exec (mandatory): never raw docker exec NAME. Always dc-exec from the project folder. kind=devcontainer app: official devcontainer exec. kind=compose app: docker compose exec of the resolved service (one service, else app, else web, else list + refuse). Other services: dc-exec --list then dc-exec --service NAME -- cmd / --id. Stopped service is started first. Restart a stack sibling: dc-exec --service NAME --restart (membership-checked). --id --restart is refused. Never docker restart a stranger.
6. Stop: dc-down = full compose stack (app + db + mitm + … + sidecars). App-only: dc-down --app. Remove stack: dc-down --rm. Nuclear: dc-down --all --yes. Old --compose is an alias for the default full stack.
7. Open: dc-open host. --attach with code = VS Code Remote URI. Without code, Zed: prints dc-up → dc-open → Project: Open Remote → Connect Dev Container (exit 0). Zed does not publish forwardPorts (dc-forward does).
8. Ports: dc-forward reconciles owned sidecars (not host socat on Colima). Host+container pair identity (9001:80 stays asymmetric). Requires exactly one labeled app or --id. Any mapping it cannot ensure fails (and fails dc-up after a successful start). Auto wanted set is still app|web only — dc-db may sidecar the db with an exact declared pair (dc-forward --id $db HOST:CONTAINER). 8b. Database: dc-db --list then dc-db / --print / --service NAME. Creds from official image env (first volume init). Stale volume → --url. Never put secrets in dc-doctor --json. 8c. Files: dc-files / --service NAME. Detects $DC_FILES_TOOL, yazi, nnn, lf, mc, ranger in the box. If none, copies a cached Linux yazi to /tmp/dc-cli-yazi and runs that. Never apt-get. Enter / double-click opens the guest path in code or cursor on this container (DC_FILES_EDITOR=code/cursor). Cursor uses dev-container+ and needs kind=devcontainer; compose-kind falls back to a bind-mount host path. Hatch: DC_FILES_EDITOR=vim. Bind-mount folder editor stays dc-open.
9. Disk: dc-df (report) → dc-prune dry-run → dc-prune --yes (engine-wide cache + dangling images + nets; owned-only orphan sidecars). Unused tagged images: dc-prune --all --yes (also engine-wide). One named volume: dc-prune --volume NAME --yes only when user names it (owned-only; mount inventory must succeed). Colima still full after prune: dc-prune --colima-hint. 9b. Stats: dc-stats / --json is read-only CPU/RAM/net for this folder. Guest is Colima/Desktop VM (Desktop live guest is cap only). Never treat Mac host RAM as the box. TUI t consumes --json. 9c. Nets: dc-net / --json / --ensure is this folder only. Create missing declared external: true names as a default bridge. Compose-managed = list only. TUI n consumes --json; y runs dc-up --create-nets.

Pitfalls

• --override-config / dc-up --ports replaces project config entirely.
• dc-down --all is nuclear; requires --yes.
• Never docker system prune -af --volumes — deletes named DB / node_modules volumes.
• Never raw docker exec NAME — use dc-exec (DC app = official CLI; compose-kind app = docker compose exec inside dc-exec).
• Restart is stack-only: dc-exec --service NAME --restart. --id --restart is refused. TUI R on the labeled app row is refused (u/s).
• Named volumes are listed by dc-df --volumes but not auto-deleted.
• Colima disk cap is a VM size; prune frees inside the VM only.
• Host port clash (e.g. two stacks both bind 9001): dc-up shows the holder; --take-ports stops labeled foreign holders or a compose-kind folder whose working_dir/config_files prove ownership (full stack via dc-down) and retries once. Unlabeled / name-only / ambiguous / inspect-unknown = report-only. Never stop same-workspace containers.
• dc-forward with two labeled apps in one folder fails closed unless you pass --id.
• Default dc-down is the whole compose project — not only the labeled app. That is intentional so host ports free up.
• Sublime cannot attach. Zed attach is first-party; dc-open --attach only prints those steps. Native Windows unsupported.
• One engine per machine. Desktop UI is not proof the CLI is talking to that VM. Do not export Colima DOCKER_HOST onto a Desktop laptop. Linux Desktop socket is ~/.docker/desktop/docker.sock. Leftover native dockerd on /var/run is a real extra engine — dc-engine --fix.

Verification

1. dc --help, dc up --help, dc-df --help, dc-prune --help, dc-up --help, dc-doctor --help, dc-recover --help, dc-upgrade --help, dc-engine --help, dc-stats --help, dc-net --help work. dc-doctor and dc-stats are read-only. dc-upgrade --check is read-only. dc-recover without --yes is read-only. dc-engine without --fix --yes is read-only. dc-net without --ensure is read-only.
2. dc-prune without --yes is dry-run (exit 0, no delete).
3. dc-prune --volume x without --yes does not delete.
4. dc-ls --json --all with no containers prints [].