# Configuring the Hindsight CLI: Environment Variables vs Config File > Understand Hindsight CLI configuration: learn how environment variables override config files and defaults for flexible setup. Optimize your CLI workflow. - Repository: [vectorize-io/hindsight](https://github.com/vectorize-io/hindsight) - Tags: how-to-guide - Published: 2026-03-13 --- **The Hindsight CLI reads configuration in a strict three-step priority chain where environment variables always override the config file, which in turn overrides the built-in default.** The `vectorize-io/hindsight` repository provides a command-line interface that supports two primary configuration methods: shell environment variables and a persistent local file. Understanding how these sources interact ensures you can manage API endpoints and credentials effectively across development, CI, and production workflows. ## Configuration Priority Chain According to the source code in [`hindsight-cli/src/config.rs`](https://github.com/vectorize-io/hindsight/blob/main/hindsight-cli/src/config.rs) (lines 35-40), the CLI resolves settings through a cascading priority system: 1. **Environment variables** (`HINDSIGHT_API_URL`, `HINDSIGHT_API_KEY`) — read first via `env::var` at the start of `Config::load` 2. **Local config file** (`~/.hindsight/config`) — parsed by `load_from_file` when env vars are absent 3. **Built-in default** (`http://localhost:8888`) — returned by `validate_and_create` as a fallback The `ConfigSource` enum (lines 28-30) tracks the origin for debugging, emitting human-readable labels like `environment variable`, `config file`, or `default`. ## Environment Variables: Temporary and Portable Environment variables provide **process-wide, temporary configuration** ideal for CI pipelines and one-off commands. ### Scope and Override Behavior Any value exported in the shell takes precedence over the config file. This allows per-command overrides without modifying persistent files: ```bash HINDSIGHT_API_URL=http://prod-api:8888 HINDSIGHT_API_KEY=sk-123 hindsight memory list ``` ### Security Considerations While convenient for automation, exported variables risk exposure via process listings (`ps e`) in shared shell sessions. However, they excel in CI environments where secrets are injected securely by the orchestration platform rather than written to disk. ### Management Configuration requires no file editing—simply `export` or `unset` variables, or prefix individual commands as shown above. ## Config File: Persistent and Secure The local config file offers **durable, user-specific settings** that persist across terminal sessions. ### File Location and Format Stored at `~/.hindsight/config`, the file uses TOML-like syntax. The `load_from_file` function (starting at line 84 in [`hindsight-cli/src/config.rs`](https://github.com/vectorize-io/hindsight/blob/main/hindsight-cli/src/config.rs)) extracts `api_url` and `api_key` values from lines 99-109. ### Security Model When written via the `hindsight configure` command or `save_config` function, the file is created with `chmod 600` permissions, restricting read access to the owner only. This reduces accidental credential exposure compared to world-readable configuration directories. ### Long-term Management Use this method for development workstations where you want every `hindsight` invocation to target the same API endpoint without prefixing commands. ## Practical Code Examples ### One-off Command with Environment Variables Override the config file temporarily for a single operation: ```bash export HINDSIGHT_API_URL=http://remote-server:8888 export HINDSIGHT_API_KEY=my-secret-key hindsight memory retain demo "Critical production note" ``` The `Config::load` implementation detects these variables immediately and skips file parsing entirely. ### Persistent Setup via Config File Create `~/.hindsight/config` manually or run `hindsight configure`: ```toml # ~/.hindsight/config api_url = "http://remote-server:8888" api_key = "my-secret-key" ``` Subsequent commands use these values automatically: ```bash hindsight memory retain demo "This uses the config file" ``` ### Mixed Mode: Environment Variables Win Even with a populated config file, environment variables take precedence: ```bash # Config file points to development cat ~/.hindsight/config | grep api_url # api_url = "http://dev-api:8888" # Override for production query HINDSIGHT_API_URL=http://prod-api:8888 hindsight memory search "deploy" ``` The CLI documentation in [`skills/hindsight-docs/references/sdks/cli.md`](https://github.com/vectorize-io/hindsight/blob/main/skills/hindsight-docs/references/sdks/cli.md) (lines 29-32) confirms this env-var shortcut behavior for users needing ad-hoc endpoint switching. ## Summary - **Priority is absolute**: Environment variables > Config file > `http://localhost:8888` default - **Use environment variables** for CI/CD pipelines, temporary testing, and scenarios requiring per-command flexibility without file modification - **Use the config file** (`~/.hindsight/config`) for persistent workstation settings with restricted file permissions (`600`) - **Mix both approaches**: Set baseline credentials in the file, then override specific commands via prefixed env vars - **Implementation lives** in [`hindsight-cli/src/config.rs`](https://github.com/vectorize-io/hindsight/blob/main/hindsight-cli/src/config.rs) with `Config::load`, `load_from_file`, and `validate_and_create` handling the resolution logic ## Frequently Asked Questions ### Can I use both environment variables and a config file simultaneously? Yes. The CLI always checks environment variables first via `env::var` in `Config::load`. If `HINDSIGHT_API_URL` or `HINDSIGHT_API_KEY` are present, they override any values in `~/.hindsight/config`. If absent, the CLI falls back to the file. This lets you store default credentials in the file while overriding specific commands with env vars. ### How does the CLI handle missing configuration? If neither environment variables nor a config file exists, `validate_and_create` returns a hardcoded default of `http://localhost:8888` for the API URL. This fallback supports quick local testing without any setup, though API calls will fail authentication unless a local server requires no key. ### Is the config file syntax strictly TOML? The `load_from_file` function implements a simple TOML-like parser (lines 84-109 in [`hindsight-cli/src/config.rs`](https://github.com/vectorize-io/hindsight/blob/main/hindsight-cli/src/config.rs)). It expects key-value pairs such as `api_url = "..."` and `api_key = "..."`. While not a full TOML parser, it handles the basic string assignments required for CLI configuration. ### What permissions does the config file use? When created via `hindsight configure` or the internal `save_config` function, the file is written with `chmod 600` (user read/write only). This permission model prevents other users on the system from reading API keys stored in `~/.hindsight/config`, mitigating risks of credential leakage through file system access.