Essential Dream CLI Commands for Managing DreamServer Services

The Dream CLI provides a unified Bash interface with sub-commands like dream status, dream logs, and dream restart that wrap Docker Compose operations to manage the entire DreamServer stack without manual container orchestration.

The DreamServer project by Light-Heart-Labs delivers a containerized AI stack for local and cloud inference. At the center of its operational workflow sits the dream command-line tool, defined in dream-server/dream-cli, which abstracts complex Docker Compose interactions into simple, memorable sub-commands for service lifecycle management mapped to Bash functions like cmd_status and cmd_restart.

Core Lifecycle Commands

The Dream CLI implements four fundamental commands that control service execution across the entire stack. These commands map directly to Docker Compose operations but enforce strict error handling via set -euo pipefail within the dream-server/dream-cli source.

dream start and dream stop bring the entire deployment up or down, equivalent to docker compose up -d and docker compose down. Use these for simple power-on and power-off operations.

dream restart [svc] restarts either the complete stack or a single container when you provide a service name. This triggers the cmd_restart function in the CLI source and is essential for applying configuration changes or recovering from crashed containers.

dream status executes health checks on every enabled service, reporting container health, GPU utilization status, and startup failures. This command calls cmd_status to aggregate data from Docker and hardware monitors into a single dashboard view.

# Start the entire DreamServer stack

dream start

# Check GPU allocation and container health across all services

dream status

# Restart only the text-to-speech service after config changes

dream restart tts

# Shut down every container cleanly

dream stop

Service Inspection and Debugging

When troubleshooting containers, the Dream CLI offers targeted visibility without requiring raw Docker syntax.

dream list displays a formatted table of core services and extensions, showing each container’s current state (running, stopped, or disabled). This invokes cmd_list to parse the active compose configuration.

dream logs <svc> streams real-time logs from a specific service using docker compose logs -f. Replace <svc> with identifiers like llm, tts, or dashboard to isolate output from a single container.

# View all active services and their states

dream list

# Follow the LLM inference container logs in real-time

dream logs llm

Extension Management

DreamServer uses a modular extension system where optional capabilities are added or removed via compose fragment injection.

dream enable <ext> activates an extension by appending its compose fragment to the base configuration, while dream disable <ext> removes it. These commands reference metadata defined in dream-server/extensions/services/<name>/manifest.yaml for validation. For example, you can enable the n8n workflow engine or disable the whisper voice-to-text service without editing files manually.

# Enable the n8n workflow automation extension

dream enable n8n

# Remove the whisper transcription service from the stack

dream disable whisper

Backend Configuration

Switching between local and cloud inference requires runtime configuration changes that the Dream CLI handles atomically.

dream mode {local|cloud|hybrid} switches the LLM backend between pure local inference, remote cloud APIs via LiteLLM, or a hybrid fallback mode. This updates the active configuration without requiring a full reinstall.

dream model swap T<N> upgrades or downgrades the running large language model to a different hardware tier (e.g., T3), triggering a container restart to load the new weights. This is useful when GPU memory availability changes.

# Switch to cloud-based inference only

dream mode cloud

# Upgrade to a higher-tier model requiring more VRAM

dream model swap T3

Configuration Snapshots

Preserve and inspect system state using the Dream CLI's configuration management utilities.

dream config show prints the current .env configuration with secrets masked, allowing safe inspection of environment variables. This reads from the active configuration files in the deployment directory.

dream preset save <name> and dream preset load <name> create and restore named snapshots of the current configuration state. These commands utilize cmd_preset_save and cmd_preset_load functions to serialize settings, enabling instant rollback after experimental changes.

# View current environment variables (credentials hidden)

dream config show

# Save current setup as "gaming" profile

dream preset save gaming

# Restore the saved configuration

dream preset load gaming

Summary

• The Dream CLI in dream-server/dream-cli wraps Docker Compose operations into manageable Bash functions like cmd_status and cmd_restart.
• Lifecycle commands (start, stop, restart, status) control service execution and health monitoring across the stack.
• Inspection tools (list, logs) provide container visibility without memorizing Docker flags.
• Extension management (enable, disable) modifies services by manipulating compose fragments defined in manifest.yaml files.
• Backend control (mode, model swap) switches inference sources and hardware-tier models dynamically.
• Configuration utilities (config show, preset) snapshot and restore environment states for safe experimentation.

Frequently Asked Questions

Where is the Dream CLI source code located?

The Dream CLI implementation resides in dream-server/dream-cli within the Light-Heart-Labs/DreamServer repository. This Bash script defines all sub-commands as discrete functions (e.g., cmd_status, cmd_list) and enforces strict error handling with set -euo pipefail to ensure failures are visible during execution.

How does dream restart differ from running docker compose restart manually?

The dream restart command provides a wrapper that accepts optional service names and integrates with the DreamServer extension system. While it ultimately calls Docker Compose operations, it respects the active configuration presets and ensures that extension manifests are re-validated, which raw Docker commands would bypass.

What file format does Dream CLI use for extension metadata?

Dream CLI expects extension metadata in YAML format within dream-server/extensions/services/<service_name>/manifest.yaml. These manifest files declare service dependencies, compose fragment paths, and configuration requirements that the dream enable and dream disable commands parse before modifying the active stack composition.

Can Dream CLI commands be used in CI/CD pipelines?

Yes, the Dream CLI is designed for automation because it returns non-zero exit codes on failure and outputs machine-friendly text. Since the script uses set -euo pipefail, pipelines can reliably use commands like dream status to gate deployments or dream preset load to standardize environment configurations across staging and production systems.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}