nGPT Configuration Priority Order: How Settings Are Merged and Overridden

nGPT applies a strict five-level hierarchy where command-line arguments override environment variables, which override CLI config files, which override main config profiles, which finally fall back to built-in defaults.

The nazdridoy/ngpt repository implements a deterministic, layered configuration system that merges multiple sources to determine final values for API keys, base URLs, models, and other runtime options. Understanding this priority chain is essential for debugging why a particular setting is active and for deploying nGPT across different environments without hardcoding credentials.

The Five-Level Configuration Priority Hierarchy

nGPT resolves configuration values through a cascading merge. When the same option is defined in multiple places, the source with the highest priority wins.

1. Command-Line Arguments (Highest Priority)

Arguments passed directly to the ngpt command always take precedence. Options like --api-key, --base-url, --model, --temperature, and --config-index are parsed first and injected into the final configuration object before any other sources are considered. This guarantees that explicit per-invocation overrides are respected regardless of environment or file-based settings.

2. Environment Variables

After CLI arguments are processed, nGPT checks for standard environment variables using the env_mapping dictionary inside the load_config function (lines 75‑88 of ngpt/core/config.py). Supported variables include:

• OPENAI_API_KEY
• OPENAI_BASE_URL
• OPENAI_MODEL

If an environment variable is present, it overwrites the value loaded from configuration files. Notably, empty strings are explicitly allowed for api_key to support local endpoints that do not require authentication.

3. CLI Configuration File (ngpt-cli.conf)

The third priority level is the dedicated CLI configuration file, ngpt-cli.conf, managed via the --cli-config sub-command. Values stored here—such as default temperature or output formatting preferences—are applied after environment variables but before the main configuration profiles. This file is distinct from the provider profiles and stores persistent defaults for the CLI interface itself.

4. Main Configuration File Profiles (ngpt.conf)

The ngpt.conf file contains a JSON list of provider profiles. The load_config function (lines 22‑63 of ngpt/core/config.py) first calls load_configs to read all profiles, then selects the appropriate entry based on either the default index (0) or an explicit choice via --config-index or --provider. If a provider name is supplied and matches multiple profiles, nGPT resolves the ambiguity interactively. Settings from the selected profile are applied only if they have not been overridden by higher-priority sources.

5. Built-in Defaults (Lowest Priority)

If a value remains undefined after all previous steps, nGPT falls back to the DEFAULT_CONFIG_ENTRY defined at lines 8‑14 of ngpt/core/config.py. These hardcoded defaults include:

• api_key: None
• base_url: https://api.openai.com/v1/
• provider: OpenAI
• model: gpt-3.5-turbo

How Configuration Overrides Are Applied in Practice

The merging process follows a specific sequence to ensure predictable behavior. According to the source code in ngpt/core/config.py and the documentation in docs/configuration.md (lines 107‑118), nGPT executes the following flow:

1. Select a profile — Choose either the default profile at index 0 or specify an alternative using --config-index or --provider.
2. Load the base profile — Read the selected entry from ngpt.conf into the configuration object.
3. Apply environment variable overrides — Walk the env_mapping and update values if corresponding variables are set.
4. Apply CLI-configuration defaults — Merge settings from ngpt-cli.conf if they exist.
5. Apply command-line arguments — Overwrite with any flags passed directly to the current command.

After this merge completes, the check_config function (lines 73‑81 of ngpt/core/config.py) validates the result. If a required field such as api_key is still None, nGPT prints a helpful error message and displays configuration help rather than failing silently.

Code Examples: Overriding nGPT Configuration

Using a Custom Profile via Index

Select the second profile defined in ngpt.conf to use a different provider or endpoint:

ngpt --config-index 1 "Summarize the latest GitHub PR"

Overriding with Environment Variables

Set the model temporarily without modifying config files. This supersedes the model defined in the selected profile:

export OPENAI_MODEL="gpt-4o"
ngpt "Explain the benefits of using environment variables for config"

Full Override with Command-Line Arguments

Override all lower-priority sources by specifying values directly. These arguments win over env vars and config files:

ngpt \
  --api-key "my-custom-key" \
  --base-url "https://custom.api/v1/" \
  --model "gpt-4-mini" \
  "Generate a Dockerfile for a Flask app"

Setting Persistent CLI Defaults

Store defaults that apply to all future invocations unless overridden by higher-priority sources:

# Store a default temperature

ngpt --cli-config set temperature 0.9

# Override per-call

ngpt --temperature 0.2 "Write a terse summary"

Interactive Configuration

Add a new profile to ngpt.conf through guided prompts:

ngpt --config

This interactively collects the API key, base URL, provider name, and model, then appends the new entry to the configuration file.

Summary

• nGPT configuration priority order follows a strict hierarchy: CLI arguments → Environment variables → CLI config file (ngpt-cli.conf) → Main config profiles (ngpt.conf) → Built-in defaults.
• The load_config function in ngpt/core/config.py orchestrates the merge, handling profile selection, environment mapping, and validation.
• Environment variables are processed via env_mapping (lines 75‑88), allowing empty strings for local endpoints.
• Command-line arguments are parsed in ngpt/cli/args.py and always take final precedence.
• Use --cli-config to set persistent defaults, --config-index to switch profiles, and --config to add new providers interactively.

Frequently Asked Questions

What happens if I set the same option in both an environment variable and a command-line argument?

Command-line arguments have higher priority than environment variables. If you run export OPENAI_MODEL=gpt-4 followed by ngpt --model gpt-3.5-turbo "hello", the model will be gpt-3.5-turbo because the CLI flag overrides the environment variable according to the priority chain in ngpt/core/config.py.

Can I use nGPT without an API key for local LLM endpoints?

Yes. The configuration system explicitly allows empty strings for api_key to support local endpoints. Set OPENAI_API_KEY="" or define an empty key in your ngpt.conf profile. The load_config function (lines 75‑88) preserves empty strings during the environment variable mapping phase.

How does nGPT handle ambiguous provider names when using --provider?

When multiple profiles in ngpt.conf share the same provider name, load_config (lines 22‑63) detects the collision and launches an interactive prompt asking you to select the correct index. This prevents accidental misconfiguration when provider names are not unique.

Where are the built-in default values defined if no configuration files exist?

Default values are hardcoded in the DEFAULT_CONFIG_ENTRY dictionary at lines 8‑14 of ngpt/core/config.py. These include the OpenAI endpoint (https://api.openai.com/v1/) and model (gpt-3.5-turbo), which serve as fallbacks only if no higher-priority source provides a value.

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