SDK Configuration

Configuration is layered. Later sources win:

defaults  <  config file  <  environment variables  <  flags

Config file

Location by OS:

OS	Path
Linux	~/.config/glacier/config.json
macOS	~/Library/Application Support/glacier/config.json
Windows	%AppData%\glacier\config.json

All keys are optional. The SDK runs with no config file present.

Minimal example:

{
  "versioncheck": {
    "cache_ttl": "1h"
  }
}

Config keys

Key	Type	Default	Description
github.repo	string	nathanbrophy/glacier	Repository used by version --check for the latest-release lookup.
versioncheck.cache_ttl	duration	24h	TTL for the cached latest-release result. Accepts Go duration strings: 1h, 30m, 24h.
versioncheck.enabled	bool	true	Set to false to disable the version --check network call entirely.
versioncheck.strict	bool	false	When true, a network failure during --check exits 68 instead of degrading gracefully.
banner.show_on_help	bool	true	Show the banner when glacier --help is invoked.
palette.override	object	{}	Per-token color overrides. Keys are CSS custom property names (e.g. "--mg-cyan": "#00ffff").

The telemetry key is hard-coded to false. Setting it has no effect. The SDK never phones home.

Environment variables

Config key overrides

Every config key maps to an environment variable with the GLACIER__ prefix and double-underscore separators:

Config key	Environment variable
github.repo	GLACIER__GITHUB__REPO
versioncheck.cache_ttl	GLACIER__VERSIONCHECK__CACHE_TTL
versioncheck.enabled	GLACIER__VERSIONCHECK__ENABLED
versioncheck.strict	GLACIER__VERSIONCHECK__STRICT
banner.show_on_help	GLACIER__BANNER__SHOW_ON_HELP

Color control

Variable	Effect
NO_COLOR	Suppress all ANSI color; equivalent to --no-color. Honored by all ANSI-aware tools.
GLACIER_NO_COLOR	Same as NO_COLOR, scoped to the Glacier SDK only.
FORCE_COLOR	Force color even when stdout is not a TTY.
GLACIER_FORCE_COLOR	Same as FORCE_COLOR, scoped to the Glacier SDK only.

Logging and verbosity

Variable	Effect
GLACIER_VERBOSE	Equivalent to --verbose (-V): raises log level to Debug.
GLACIER_DEBUG	Equivalent to --very-verbose: raises log level to Trace.

Telemetry (opt-in)

Variable	Effect
OTEL_EXPORTER_OTLP_ENDPOINT	When set, the SDK initializes obs and emits per-command spans and counters to this endpoint. No data is sent when this variable is unset.

Global flags

These flags are accepted by every command and take precedence over all other sources.

Flag	Short	Description
--help	-h	Print help text
--quiet	-q	Suppress non-error output and animations; keep the final summary
--verbose	-V	Raise log level to Debug
--very-verbose		Raise log level to Trace
--no-animate		Force plain output even on a TTY
--no-banner		Suppress the banner on this invocation
--no-color		Disable all ANSI color output
--force-color		Force color output even when output is not a TTY
--profile		Write pprof CPU, heap, and goroutine profiles
--otel-endpoint		Override OTEL_EXPORTER_OTLP_ENDPOINT for this invocation

--quiet and --verbose / --very-verbose are mutually exclusive. Combining them exits 2.

-v is reserved for --version on the root command.

Exit codes

Code	Meaning
0	Success
1	Generic failure
2	Usage error
64	Generator failure (generate)
65	Lint findings at or above the severity threshold (lint)
66	Tests failed or benchmark regression detected (test)
67	Scaffolding failure (init, new)
68	Version-check unreachable when --strict is set (version --check --strict)
69	Codegen drift detected (generate --check)
70	Subprocess failure (wrapped tool exited non-zero)
130	SIGINT / Ctrl-C
143	SIGTERM

Exit codes are stable across SDK versions. Use glacier explain <code> to read the full description and suggested next steps.

Cache files

File	Owner command	Purpose
<UserCacheDir>/glacier/versioncheck.json	version	Latest-release lookup result, cached with TTL
<repo>/.glacier/lint-cache.json	lint	Per-file content-hash result cache
<repo>/.glacier/bench-baseline.json	test --bench	Benchmark baseline for regression gating
<repo>/.glacier/coverage.out	test --cover	Coverage profile

<repo>/.glacier/ is added to the .gitignore generated by glacier init. All cache writes route through internal/safefile for atomic replacement.