DOCK<

Reference

CLI Command Reference

Complete reference for status, plan, sync, init, flags, and config path arguments in Dock.

Command Overview

Dock provides explicit CLI commands designed for transparent, repeatable local container lifecycle management.

dock validateValidates dock.yaml schema and syntax only. Does not check or install host prerequisites.
dock statusReports host requirements, Docker daemon state, and status of Dock-managed containers (supports --running / --stopped).
dock planConcise list of pending prerequisite installations and application provisioning actions (supports --json).
dock syncFull read-only comparison between dock.yaml and local state, previewing planned changes.
dock initApplies configuration: installs host prerequisites, pulls/builds images, creates/starts containers, and checks health.
dock startStarts stopped Dock-managed project containers.
dock stopStops Dock-managed containers while preserving container state.
dock logsDisplays recent stdout/stderr container logs (accessible even after the container stops).
dock -vPrints the installed Dock CLI version.

Specifying Configuration Paths

All commands that inspect or apply configuration accept an optional config path. The supported forms are:

  • Positional argument: dock validate ./configs/dock.yaml
  • Short flag -c PATH: dock init -c ./configs/dock.yaml
  • Long flag --config PATH: dock status --config ./configs/dock.yaml

Detailed Command Explanations

dock status

Shows the selected project's current system environment, Docker daemon connectivity, requirement satisfaction, and Dock-managed container status.

  • dock status --running: Filters the container section to running containers for the selected project.
  • dock status --stopped: Filters the container section to non-running (stopped/exited) containers for the selected project.
  • --running and --stopped are mutually exclusive.
terminal
$ dock status -c ./dock.yaml
Project: hello-nginx
System Requirements: git, curl (Satisfied)
Docker Daemon: Running
Containers:
  - dock-hello-nginx (Up 5m, Port 8080 -> 80)

$ dock status --running -c ./dock.yaml
Project: hello-nginx
Containers (Running):
  - dock-hello-nginx (Up 5m, Port 8080 -> 80)

$ dock status --stopped -c ./dock.yaml
Project: hello-nginx
Containers (Stopped):
  (No stopped containers for this project)

dock plan

Produces a concise list of pending prerequisite installations and application provisioning actions needed to reconcile the local state with your dock.yaml specification.

  • Distinct from sync: dock plan is no longer an alias for dock sync. It provides a focused list of upcoming actions rather than a full state inspection matrix.
  • Up-to-Date Reporting: If the environment and container are already fully provisioned and up to date, dock plan clearly states that no changes are needed.
  • JSON Mode: Use dock plan --json to output the plan in structured JSON format for scripting and automation.
terminal
$ dock plan -c ./dock.yaml
Plan (hello-nginx):
  - Pull image: nginx:alpine
  - Create container: dock-hello-nginx
  - Map ports: 8080:80
  - Verify HTTP healthcheck: / on port 80

$ dock plan --json -c ./dock.yaml
{
  "project": "hello-nginx",
  "status": "pending_changes",
  "actions": [
    { "type": "pull_image", "image": "nginx:alpine" },
    { "type": "create_container", "name": "dock-hello-nginx", "ports": [{ "host": 8080, "container": 80 }] },
    { "type": "healthcheck", "protocol": "http", "path": "/", "port": 80 }
  ]
}

dock sync

Shows the fuller, comprehensive comparison between the selected configuration in dock.yaml and the current system/project state, detailing both matching elements and planned changes.

terminal
$ dock sync -c ./dock.yaml
State Comparison (hello-nginx):
  [✓] System Packages: git (installed)
  [✓] Docker Daemon: running
  [!] Image: nginx:alpine (not cached, will pull)
  [!] Container: dock-hello-nginx (not found, will create)
  [!] Ports: 8080 -> 80 (available)
  [!] Healthcheck: http GET / on 80 (configured)

dock init

Applies the changes: installs supported host prerequisites, pulls or builds the container image, starts the container with configured port bindings, and verifies the HTTP health check.

terminal
$ dock init -c ./dock.yaml
✓ Image pulled: nginx:alpine
✓ Container dock-hello-nginx created and started
✓ HTTP health check passed (http://localhost:8080/)

Understanding the Inspection Commands

CommandPrimary PurposeFlagsModifies State?
dock statusCurrent live state of system, Docker & project containers--running, --stoppedNo (Read-only)
dock planConcise action list of pending prerequisite installs & provisioning--jsonNo (Read-only)
dock syncFull state comparison between config and local environment-c / --configNo (Read-only)
dock initExecutes the plan: pulls, builds, runs containers & checks health-c / --configYes (Applies changes)

dock logs

Fetches stdout and stderr output from the project container. Because Docker retains stopped containers until removed, dock logs can still read output from a stopped container.

Windows PowerShell Syntax

PowerShell
> dock validate -c .\configs\dock.yaml
> dock plan -c .\configs\dock.yaml
> dock sync --config .\configs\dock.yaml
> dock init -c .\configs\dock.yaml
> dock status --running -c .\configs\dock.yaml
> dock logs -c .\configs\dock.yaml

Features Not in V1 (Planned for Future Versions)