CLI Reference

DSO is implemented as a native Docker CLI plugin. All interactions are performed via the docker dso command space.

---

Command: up

Synchronizes secrets and initializes a Docker Compose stack.

docker dso up -c dso.yaml -f docker-compose.yml -d

Mechanics:

1. Pre-flight: Parses dso.yaml and establishes a connection to the dso-agent via the Unix socket.
2. Resolution: Fetches the latest secret values from the configured provider (AWS/Azure/Vault).
3. Injection: Maps secret values to the environment of services defined in docker-compose.yml.
4. Execution: Calls docker compose up with the enriched environment.

Common Flags:

• -d, --detach: Run containers in the background.
• -c, --config: Path to a custom dso.yaml (Default: ./dso.yaml).
• -f, --file: Path to a custom docker-compose.yml.

---

Command: validate

Performs a structural and connectivity check on your configuration without starting any containers.

docker dso validate -c dso.yaml

Mechanics:

1. Schema Check: Validates the dso.yaml syntax against the official JSON schema.
2. Provider Probe: Attempts to authenticate with the cloud provider (AWS/Huawei/Vault) to verify IAM/Permissions.
3. Mapping Audit: Checks if all environment variables mapped in dso.yaml exist in the target docker-compose.yml.

---

Command: down

Stops the stack and performs a secure memory purge.

docker dso down [compose-args...]

Mechanics:

1. Termination: Calls docker compose down to stop and remove containers.
2. Purge: Signals the dso-agent to flush the sensitive secret cache from its process memory.

---

Command: fetch

Resolves and displays a specific secret (for debugging purposes).

docker dso fetch <secret-name>

Usage: Use this command to verify that your host has the correct IAM permissions or API access to reach the vault before launching a full stack. Note: Secret values are masked in the terminal output to prevent "shoulder surfing" leaks.

---

Command: watch

Starts the Watcher Engine in foreground mode.

docker dso watch

Usage: Ideal for debugging rotation strategies and SIGHUP signals. The command streams real-time reconciliation logs, showing exactly when a secret drift is detected and how the Reloader Controller responds.

---

Command: version

Displays the DSO binary version and build metadata.

docker dso version

---

Global Configuration Resolution

DSO resolves its configuration using the following priority:

1. Explicit flag via --config.
2. Environment variable DSO_CONFIG.
3. Local file ./dso.yaml.
4. System-wide file /etc/dso/dso.yaml.

Next Steps

• System Architecture: Learn how the CLI interacts with the Agent.
• Configuration Reference: Detailed dso.yaml schema.
• Security Model: How the CLI-to-Agent socket is protected.