Dream CLI Model Management Commands: Inspecting and Switching Local LLM Tiers

The Dream CLI provides three sub-commands (current, list, and swap) under the model namespace to inspect active models and switch between hardware-optimized tiers without manually editing configuration files.

The DreamServer repository from Light-Heart-Labs delivers a production-grade inference stack with a comprehensive command-line interface for local LLM administration. The Dream CLI model management commands enable operators to query the active model, enumerate compatible hardware tiers, and perform hot-swaps of GGUF files through a unified Bash interface defined in dream-server/dream-cli.

Available Model Management Commands

The model sub-command group in dream-cli (source) exposes three primary operations for runtime model administration.

dream model current

The current command displays the active LLM model by reading the LLM_MODEL variable from the .env configuration file. It utilizes the internal helper function _env_get_raw to retrieve raw environment values and prints the currently loaded GGUF identifier to stdout.

dream model list

The list command enumerates all available model tiers compatible with the detected hardware backend. It sources installers/lib/tier-map.sh to resolve tier names (T0-T4, SH, SH_LARGE, NV_ULTRA, and others) into their corresponding model identifiers. This allows administrators to view capacity options before committing to a swap.

dream model swap

The swap command transitions the server to a new model tier by updating the .env configuration. It validates the requested tier, calls tier_to_model from tier-map.sh to resolve the logical name to a concrete GGUF filename, and writes the change via _env_set. The command outputs the resolved model name and prompts the user to execute dream restart llama-server to load the new weights.

Internal Implementation Details

The model management logic resides in the cmd_model function within dream-server/dream-cli. The implementation relies on a separation between tier abstraction and physical model files.

The tier-map library (installers/lib/tier-map.sh) provides pure-function mappings that translate human-readable tier codes into specific GGUF filenames and context sizes. When swapping, the CLI updates LLM_MODEL, GGUF_FILE, and CTX_SIZE entries in dream-server/.env, ensuring the llama-server service reads the correct parameters on next startup.

Practical Usage Examples

Execute these commands from the dream-server directory to manage your local inference stack:

# Display the currently active model

dream model current
#> Current model: Qwen3.5-9B-Q4_K_M.gguf

# List hardware-compatible tiers

dream model list
#> T0  → Llama‑3‑8B‑GGUF
#> T1  → Qwen3‑9B‑GGUF
#> T2  → Qwen3‑30B‑GGUF
#> T3  → Qwen3‑30B‑A3B‑GGUF

# Switch to a higher-capacity tier

dream model swap T3
#> Model set to Qwen3.5-9B-Q4_K_M.gguf (tier T3, ctx=8192)
#> Run 'dream restart llama-server' to apply.

After running dream model swap, you must restart the inference service to unload the previous weights and load the new GGUF file into VRAM.

Summary

• The Dream CLI provides three model management commands: current to inspect the active model, list to view compatible tiers, and swap to change configurations.
• Command logic is implemented in dream-server/dream-cli using helper functions _env_get_raw and _env_set to manipulate the .env file safely.
• Tier resolution depends on installers/lib/tier-map.sh, which maps abstract tiers (T0-T4, SH, etc.) to concrete GGUF filenames.
• Model swaps require a subsequent dream restart llama-server to apply changes, as the CLI only updates persistent configuration rather than performing runtime model hot-loading.

Frequently Asked Questions

How do I check which model is currently active?

Run dream model current to query the LLM_MODEL variable from your .env file. This command returns the GGUF filename currently configured for the llama-server service without parsing or validating the file's existence on disk.

What hardware tiers are supported by the Dream CLI?

The CLI supports tiers T0 through T4, alongside specialized codes like SH, SH_LARGE, and NV_ULTRA. The exact list visible via dream model list varies based on your hardware detection results, as the command filters tiers against your GPU VRAM and CPU capabilities using the logic in tier-map.sh.

Why do I need to restart the server after swapping models?

The dream model swap command only updates persistent configuration values in .env (specifically LLM_MODEL, GGUF_FILE, and CTX_SIZE). The llama-server process loads weights into memory at startup and does not support runtime model hot-swapping; therefore, you must execute dream restart llama-server to terminate the existing process and spawn a new instance with the updated environment.

Where are the model tier mappings defined?

Tier-to-model mappings reside in installers/lib/tier-map.sh within the DreamServer repository. This library exports the tier_to_model function used by the CLI to resolve abstract tier names into specific GGUF filenames and context window sizes appropriate for your detected hardware backend.

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