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

> Manage local LLM tiers with Dream CLI model commands. Inspect current models, list available tiers, and swap hardware-optimized models easily.

- Repository: [Light Heart Labs/DreamServer](https://github.com/Light-Heart-Labs/DreamServer)
- Tags: how-to-guide
- Published: 2026-05-18

---

**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](https://github.com/Light-Heart-Labs/DreamServer/blob/main/dream-server/dream-cli#L2578‑L2638)) 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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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 <tier>

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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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:

```bash

# Display the currently active model

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

```

```bash

# 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

```

```bash

# 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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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.