# DeepSeek TUI Configuration System: Profiles and Environment Variable Overrides > Master DeepSeek TUI configuration using profiles and environment variable overrides. Learn how settings hierarchy ensures ultimate control over your DeepSeek TUI environment. - Repository: [Hunter Bown/DeepSeek-TUI](https://github.com/Hmbown/DeepSeek-TUI) - Tags: how-to-guide - Published: 2026-05-04 --- **DeepSeek TUI loads its runtime settings from a four-layer hierarchy where CLI flags take precedence over environment variables, which in turn override TOML configuration profiles and built-in defaults.** The DeepSeek TUI (`Hmbown/DeepSeek-TUI`) provides a deterministic, multi-layered configuration system designed for both interactive use and CI/CD automation. It merges global settings, per-project overlays, named profiles, and environment-specific overrides to determine final runtime behavior, all implemented in the [`crates/config/src/lib.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/config/src/lib.rs) core library. ## Configuration File Locations and Structure DeepSeek TUI reads TOML configuration from two primary locations, merging them sequentially. First, the global configuration at `~/.deepseek/config.toml` establishes base settings. Second, if the TUI starts inside a Git workspace containing [`.deepseek/config.toml`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/.deepseek/config.toml), those values are merged on top via the `load_project_config` function (lines 776–787 of [`crates/config/src/lib.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/config/src/lib.rs)). This overlay can replace the entire `providers` table or specific fields without modifying your global settings. A valid configuration file contains top-level keys (e.g., `api_key`, `default_text_model`) and optional nested tables for `providers` and `profiles`: ```toml api_key = "PERSONAL_KEY" default_text_model = "deepseek-v4-pro" base_url = "https://api.deepseek.com" [providers.deepseek] api_key = "PROVIDER_SPECIFIC_KEY" [profiles.work] api_key = "WORK_KEY" base_url = "https://enterprise.deepseek.com" ``` ## Understanding Configuration Precedence The resolver follows a strict precedence order to guarantee predictable behavior. When a key is defined in multiple layers, the system picks the value from the highest-priority layer that defines it: 1. **CLI flags** (e.g., `--model`, `--profile`) – Highest priority. 2. **Environment variables** (e.g., `DEEPSEEK_API_KEY`) – Override file settings. 3. **Configuration file** – Merged global, project, and active profile values. 4. **Built-in defaults** – Hardcoded provider URLs and models (e.g., NVIDIA NIM defaults to `https://integrate.api.nvidia.com/v1`) – Lowest priority. The `resolve_runtime_options` function (lines 602–630 of [`crates/config/src/lib.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/config/src/lib.rs)) implements this logic, checking CLI overrides first, then `EnvRuntimeOverrides`, then file-based values, and finally falling back to provider-specific defaults defined at lines 690–698. ## Working with Profiles Profiles allow you to define isolated configuration sets for different contexts (e.g., "work", "personal", or "nvidia-nim") within a single file. A profile is a named table under the `[profiles]` section. It can contain any top-level key, including `api_key`, `base_url`, `provider`, or `default_text_model`. ```toml [profiles.nvidia-nim] provider = "nvidia-nim" api_key = "NVIDIA_KEY" base_url = "https://integrate.api.nvidia.com/v1" default_text_model = "deepseek-ai/deepseek-v4-pro" ``` Activate a profile using the `--profile` flag or the `DEEPSEEK_PROFILE` environment variable: ```bash deepseek --profile nvidia-nim # or export DEEPSEEK_PROFILE=nvidia-nim deepseek ``` If the requested profile does not exist, the TUI aborts with a clear error listing available profiles. ## Environment Variable Overrides All top-level configuration keys map to a `DEEPSEEK_*` environment variable, read by `EnvRuntimeOverrides::load`. These variables override any value coming from the file, regardless of whether a profile is active. Common environment variables include: - **`DEEPSEEK_API_KEY`** – Overrides the global `api_key` (or provider-specific key when a provider is selected). - **`DEEPSEEK_BASE_URL`** – Overrides the global `base_url`. - **`DEEPSEEK_MODEL`** or **`DEEPSEEK_DEFAULT_TEXT_MODEL`** – Overrides the `default_text_model` setting. - **`DEEPSEEK_PROVIDER`** – Forces a specific provider (`deepseek`, `nvidia-nim`, `fireworks`, etc.). - **`DEEPSEEK_ALLOW_SHELL`** – Enables the sandboxed shell tool when set to `true` or `1`. - **`DEEPSEEK_APPROVAL_POLICY`** – Sets the runtime approval policy (`on-request`, `untrusted`, `never`). - **`DEEPSEEK_SANDBOX_MODE`** – Sets the sandbox level (`read-only`, `workspace-write`, `danger-full-access`). Provider-specific variables (e.g., `NVIDIA_NIM_API_KEY`, `FIREWORKS_BASE_URL`) override values inside the corresponding provider sub-tables without needing to specify a profile. ## Runtime Resolution in Code You can programmatically resolve the final configuration using the Rust API exposed in [`crates/config/src/lib.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/config/src/lib.rs). This is useful for building tools that need to verify settings before launching the TUI: ```rust use deepseek_config::ConfigStore; use deepseek_config::{CliRuntimeOverrides, ProviderKind}; let store = ConfigStore::load(None).unwrap(); // Loads ~/.deepseek/config.toml let cli = CliRuntimeOverrides { provider: Some(ProviderKind::NvidiaNim), model: Some("deepseek-v4-flash".into()), ..Default::default() }; // Returns final merged options let opts = store.config.resolve_runtime_options(&cli); ``` The `resolve_runtime_options_with_secrets` variant handles sensitive values like API keys securely. ## Practical Configuration Examples ### Define Multiple Profiles Create `~/.deepseek/config.toml` with distinct settings for work and personal use: ```toml api_key = "PERSONAL_KEY" default_text_model = "deepseek-v4-pro" [profiles.work] api_key = "WORK_KEY" base_url = "https://api.deepseek.com" ``` ### Switch Contexts via Command Line Override the active profile for a single invocation: ```bash deepseek --profile work # Uses WORK_KEY and work base URL ``` ### Temporarily Override with Environment Variables Change a setting for the current shell session without editing files: ```bash export DEEPSEEK_MODEL=deepseek-v4-flash deepseek # Runs with the flash model regardless of profile ``` ### Demonstrate Precedence CLI flags win over environment variables, which win over profiles: ```bash export DEEPSEEK_MODEL=deepseek-v4-pro deepseek --profile work --model deepseek-v4-flash # Result: model is "deepseek-v4-flash" (CLI flag takes precedence) ``` ## Summary - **Four-layer hierarchy:** CLI flags > Environment variables > Config file (global + project + profile) > Built-in defaults. - **Project overlays:** Per-project [`.deepseek/config.toml`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/.deepseek/config.toml) files are merged over global settings via `load_project_config`. - **Profile activation:** Use `[profiles.name]` tables and activate with `--profile` or `DEEPSEEK_PROFILE`. - **Env mapping:** All config keys have a `DEEPSEEK_*` equivalent that overrides file values, implemented in `EnvRuntimeOverrides`. ## Frequently Asked Questions ### What is the exact order of precedence for DeepSeek TUI configuration? The resolver evaluates options in this order: CLI flags have the highest priority, followed by environment variables, then configuration file values (merged global, project overlay, and active profile), and finally hardcoded built-in defaults. This logic is centralized in the `resolve_runtime_options` function in [`crates/config/src/lib.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/config/src/lib.rs). ### How do I create and activate a configuration profile? Add a `[profiles.]` table to your `~/.deepseek/config.toml` file containing the keys you want to override. Activate it by passing `--profile ` to the `deepseek` command or by setting the `DEEPSEEK_PROFILE=` environment variable. If the profile name is invalid, the application exits with a list of available profiles. ### Can I use environment variables for all configuration settings? Yes. Any top-level TOML key can be set via an environment variable using the `DEEPSEEK_` naming convention. For example, `DEEPSEEK_API_KEY` overrides the `api_key` field, and `DEEPSEEK_ALLOW_SHELL` controls sandboxed shell execution. Provider-specific keys use the pattern `_API_KEY` (e.g., `NVIDIA_NIM_API_KEY`). ### Where does DeepSeek TUI look for configuration files? The system first loads the global configuration from `~/.deepseek/config.toml`. If executed within a Git repository, it searches for `/.deepseek/config.toml` and merges those settings over the global ones. This merging logic is handled by the `load_project_config` implementation in [`crates/config/src/lib.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/config/src/lib.rs).