Configuring the Hindsight CLI: Environment Variables vs Config File

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 (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:

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) 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:

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:

# ~/.hindsight/config

api_url = "http://remote-server:8888"
api_key = "my-secret-key"

Subsequent commands use these values automatically:

hindsight memory retain demo "This uses the config file"

Mixed Mode: Environment Variables Win

Even with a populated config file, environment variables take precedence:

# 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 (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 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). 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.

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