# How to Manage Hister Configuration Using Environment Variables

> Manage Hister configuration with environment variables. Override defaults easily for containerized deployments without touching YAML files. Streamline your setup today.

- Repository: [Adam Tauber/hister](https://github.com/asciimoo/hister)
- Tags: how-to-guide
- Published: 2026-09-01

---

**Hister leverages environment variables to override or augment default configuration at runtime, enabling containerized deployments without editing YAML files.**

Hister (Instantaneous History Tracker) is an open-source history tracking application that supports **Hister configuration environment variables** to customize runtime behavior. According to the asciimoo/hister source code, the application inspects specific environment variables before loading configuration files, allowing operators to define custom data directories, ports, and logging levels dynamically.

## Essential Environment Variables

Hister recognizes several environment variables that control file paths, network settings, and output formatting. These variables are evaluated at startup in [`cmd/root.go`](https://github.com/asciimoo/hister/blob/main/cmd/root.go) and [`config/config.go`](https://github.com/asciimoo/hister/blob/main/config/config.go), taking precedence over values defined in YAML or TOML configuration files.

### HISTER_CONFIG

The `HISTER_CONFIG` variable specifies an explicit path to a configuration file, bypassing the default platform-specific search paths. When set, Hister loads this file instead of searching in directories like `$XDG_CONFIG_HOME` or `%APPDATA%`.

In [`cmd/root.go`](https://github.com/asciimoo/hister/blob/main/cmd/root.go) at line 439, the application checks this variable before resolving standard config directories. If the path is invalid, Hister exits with an error rather than falling back to defaults.

```bash
export HISTER_CONFIG=/etc/hister/production.yaml
hister serve

```

### HISTER_DATA_DIR

The `HISTER_DATA_DIR` variable overrides the base directory for all persistent data, including the history database, downloads, and cache files. By default, Hister resolves this from OS-specific user data directories such as `$XDG_DATA_HOME` on Linux or `%APPDATA%` on Windows.

As implemented in [`config/config.go`](https://github.com/asciimoo/hister/blob/main/config/config.go) at line 638, setting this variable redirects all file I/O operations to the specified path, making it essential for containerized deployments with mounted volumes.

```bash
export HISTER_DATA_DIR=/var/lib/hister
hister serve

```

### HISTER_PORT

The `HISTER_PORT` variable controls the HTTP port on which the server listens, defaulting to `8080` if unspecified. This setting is processed in [`config/config.go`](https://github.com/asciimoo/hister/blob/main/config/config.go) at line 642 and overrides any port defined in the loaded configuration file.

This variable is useful when running multiple instances on the same host or deploying behind reverse proxies with specific port requirements.

```bash
export HISTER_PORT=9090
hister serve  # Starts server on http://localhost:9090

```

### HISTER__APP__LOG_LEVEL

The `HISTER__APP__LOG_LEVEL` variable adjusts the verbosity of the application logger, accepting standard levels: `debug`, `info`, `warn`, or `error`. The default level is `info` unless overridden by the configuration file.

According to [`cmd/root.go`](https://github.com/asciimoo/hister/blob/main/cmd/root.go) at line 421, this variable configures the global logger before any commands execute. Setting this to `debug` enables request tracing and internal state dumps.

```bash
export HISTER__APP__LOG_LEVEL=debug
hister serve

```

### NO_COLOR

The `NO_COLOR` variable disables ANSI color output when set to any non-empty value. Hister checks this variable in [`cmd/tui/theme/theme.go`](https://github.com/asciimoo/hister/blob/main/cmd/tui/theme/theme.go) at line 232, stripping escape codes from terminal output to produce plain text suitable for log aggregation systems.

```bash
export NO_COLOR=1
hister version  # Outputs plain text without color codes

```

### Test-Specific Variables

The `HISTER_LIVE_CASE` and `HISTER_LIVE_ARTIFACT_DIR` variables are used exclusively by the test harness in [`server/extractor/live_test.go`](https://github.com/asciimoo/hister/blob/main/server/extractor/live_test.go). These variables select specific integration test cases and define temporary storage locations for test artifacts during live testing scenarios.

```bash
export HISTER_LIVE_CASE="case42"
export HISTER_LIVE_ARTIFACT_DIR="/tmp/hister-test"
go test ./server/extractor -run TestLive

```

## Configuration Precedence Hierarchy

Hister applies a three-tier precedence system when resolving configuration values:

1. **Environment variables** – Values set in the shell environment take highest priority and override corresponding settings in any configuration file.
2. **Explicit configuration file** – When `HISTER_CONFIG` is set, Hister loads that specific file instead of searching platform-specific default locations.
3. **Platform-specific defaults** – If no environment variable or explicit file overrides apply, Hister falls back to standard OS directories like `$XDG_CONFIG_HOME/hister` on Linux or `%APPDATA%\hister` on Windows.

This hierarchy ensures that temporary overrides supersede persistent configuration while providing sensible defaults for fresh installations.

## Practical Deployment Examples

### Local Development with Custom Paths

Run Hister locally with a dedicated data directory and non-standard port to avoid conflicts with other services:

```bash
export HISTER_DATA_DIR="$HOME/.hister-data"
export HISTER_PORT="9090"
export HISTER__APP__LOG_LEVEL="debug"
hister serve

```

This configuration isolates development data from production instances and enables verbose logging for troubleshooting.

### Docker Container Configuration

In containerized deployments, mount configuration files and data volumes while using environment variables to specify paths:

```dockerfile
FROM ghcr.io/asciimoo/hister:latest
ENV HISTER_CONFIG=/etc/hister/custom.yaml
ENV HISTER_DATA_DIR=/data
ENV HISTER_PORT=8080
COPY custom.yaml /etc/hister/custom.yaml
VOLUME /data
EXPOSE 8080
CMD ["hister", "serve"]

```

The `HISTER_CONFIG` variable ensures Hister reads the bundled configuration file, while `HISTER_DATA_DIR` redirects persistent storage to the Docker volume.

### CI/CD Pipeline Integration

For automated testing environments where color codes interfere with log parsing:

```bash
export NO_COLOR=1
export HISTER__APP__LOG_LEVEL=warn
export HISTER_DATA_DIR=$(mktemp -d)
hister serve &

# Run integration tests...

```

This setup produces clean, monochrome logs and minimizes verbosity while using a temporary data directory that gets cleaned up automatically.

## Summary

- **Hister configuration environment variables** provide runtime overrides for file paths, ports, and logging without modifying YAML files.
- The `HISTER_CONFIG` variable specifies an alternative configuration file path, processed in [`cmd/root.go`](https://github.com/asciimoo/hister/blob/main/cmd/root.go) before standard directory searches.
- Data directory and port settings are controlled by `HISTER_DATA_DIR` and `HISTER_PORT`, defined in [`config/config.go`](https://github.com/asciimoo/hister/blob/main/config/config.go) at lines 638 and 642.
- Log verbosity is managed through `HISTER__APP__LOG_LEVEL`, while `NO_COLOR` disables terminal formatting in [`cmd/tui/theme/theme.go`](https://github.com/asciimoo/hister/blob/main/cmd/tui/theme/theme.go).
- Environment variables take precedence over configuration file values, which in turn override platform-specific defaults.

## Frequently Asked Questions

### How do I change the port that Hister listens on?

Set the `HISTER_PORT` environment variable to the desired port number before starting the server. As defined in [`config/config.go`](https://github.com/asciimoo/hister/blob/main/config/config.go) at line 642, this variable overrides the default `8080` port and any port specified in configuration files. For example, `export HISTER_PORT=9090` configures the server to listen on port 9090.

### Can I specify a custom configuration file location without editing the default config?

Yes. Set the `HISTER_CONFIG` environment variable to the absolute path of your YAML or TOML file. According to [`cmd/root.go`](https://github.com/asciimoo/hister/blob/main/cmd/root.go) at line 439, Hister checks this variable during initialization and loads the specified file instead of searching default platform directories like `$XDG_CONFIG_HOME`.

### What happens if both an environment variable and a config file define the same setting?

Environment variables always take precedence. When Hister starts, it loads the configuration file (either the default or one specified by `HISTER_CONFIG`) and then overlays any environment variable values. This precedence order ensures that temporary shell overrides supersede persistent file settings without modifying stored configurations.

### How do I disable colored output in Hister logs for my logging system?

Set the `NO_COLOR` environment variable to any non-empty value, such as `1` or `true`. Hister checks this variable in [`cmd/tui/theme/theme.go`](https://github.com/asciimoo/hister/blob/main/cmd/tui/theme/theme.go) at line 232 and disables ANSI escape codes when present, producing plain text output suitable for log aggregation services and CI/CD pipelines that do not support color formatting.