How to Manage Hister Configuration Using Environment Variables

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 and 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 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.

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 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.

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 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.

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 at line 421, this variable configures the global logger before any commands execute. Setting this to debug enables request tracing and internal state dumps.

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 at line 232, stripping escape codes from terminal output to produce plain text suitable for log aggregation systems.

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. These variables select specific integration test cases and define temporary storage locations for test artifacts during live testing scenarios.

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:

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:

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:

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 before standard directory searches.
• Data directory and port settings are controlled by HISTER_DATA_DIR and HISTER_PORT, defined in 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.
• 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 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 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 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.

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