Environment variables

Use environment variables for a single invocation or an environment-wide preference. Runtime settings generally override Git and Pkl settings; CLI flags take precedence. See configuration precedence.

Boolean settings accept 1/true and 0/false. List settings use commas. Set hk’s variables in the environment that launches hk; hook and step env blocks are for child commands.

Common overrides:

HK_PROFILE=slow hk check --all
HK_SKIP_STEPS=eslint hk check
HK_LOG=debug hk run pre-commit

HK

Type: boolean · Default: enabled in installed launchers

Set HK=0 to bypass hk’s installed Git hook launcher for one command, for example HK=0 git commit. This is handled by the launcher, not by every direct hk invocation.

HK_CACHE

Type: boolean · Default: true in release builds; false in debug builds

Enable or disable the evaluated-configuration cache. Use HK_CACHE=0 hk validate when diagnosing stale configuration, or hk cache clear to remove hk’s cache.

HK_CACHE_DIR

Type: path · Default: platform cache directory plus hk

Directory for cached configuration and other cache files. On Linux this is typically ~/.cache/hk; on macOS it is typically ~/Library/Caches/hk.

HK_CHECK

Type: boolean · Default: false

Request check commands instead of fix commands. This setting wins when both HK_CHECK and HK_FIX are enabled; explicit --check and --fix flags take precedence. Check commands should leave files unchanged, but hk does not enforce that convention.

HK_CHECK_FIRST

Type: boolean · Default: true

Allow steps to run their check before fixing and skip the fix when the check passes. Steps do this when they set check_first = true (and another step writes the same files), and always when their check and fix are the same command, as in steps migrated from pre-commit. Setting this to false turns it off for both; such a migrated fixer then fails whenever it fixes something, because it exits 1 after fixing.

Some steps check first regardless of this setting, because fixing or staging depends on it: a step with check_diff in fix mode applies the diff instead of running fix, and in a hook that stages its fixes, a step with check_diff or check_list_files lists the files it would change so only those are fixed and staged. With the default stage, that happens only when one of the step's files has unstaged changes that hk didn't stash.

HK_CONFIG_DIR

Type: path · Default: $XDG_CONFIG_HOME/hk or ~/.config/hk

Directory containing the user config.pkl. See user configuration for discovery and legacy paths.

HK_DISPLAY_SKIP_REASONS

Type: comma-separated strings · Default: profile-not-enabled

Select skip reasons to display. Use hk check --why <step> for a detailed explanation of a particular step’s selection.

HK_EXCLUDE

Type: comma-separated patterns · Default: empty

Exclude files or directories from processing. These patterns combine with exclusions from other sources. Example: HK_EXCLUDE='node_modules,dist,**/*.min.js' hk check --all.

HK_FAIL_FAST

Type: boolean · Default: true

Stop remaining work after a failure. Use HK_FAIL_FAST=0 hk check --all or --no-fail-fast to collect failures from remaining steps.

HK_FILE

Type: path · Default: automatic project config discovery

Select a specific Pkl configuration instead of searching for hk.local.pkl or hk.pkl. Example: HK_FILE=./config/ci.pkl hk check --all.

HK_FIX

Type: boolean · Default: true

Permit fix mode when the hook requests it. Setting this to false disables configured fixes unless an explicit fix flag overrides it. A value of true does not make a normal hk check run fixes. HK_CHECK=1 takes precedence when both settings are enabled.

HK_HIDE_WARNINGS

Type: comma-separated tags · Default: empty

Suppress named warning categories, such as missing-profiles or local-config-replaces-shared. Suppressed tags combine across configuration sources.

HK_HIDE_WHEN_DONE

Type: boolean · Default: false

Hide progress output after a successful hook finishes. Failed runs keep their diagnostics.

HK_JOBS

Type: nonnegative integer · Default: 0 (detect CPU count)

Limit concurrent hk jobs. Example: HK_JOBS=4 hk check --all. Linters can also start their own workers, so increasing this value does not always improve speed.

HK_JSON

Type: boolean · Default: false

Request JSON output for commands that support it. For execution plans, use hk check --plan --json. For trace events, use HK_TRACE=json; this setting does not turn arbitrary linter output into structured results.

HK_LIBGIT2

Type: boolean · Default: true

Use libgit2 for Git operations where supported. Set HK_LIBGIT2=0 to use the Git CLI backend, for example when comparing performance with Git’s fsmonitor integration.

HK_LOG

Type: log level · Default: info

Console log level: off, error, warn, info, debug, or trace. HK_LOG_LEVEL is also accepted. Use hk check -v for debug output or -vv for trace logging.

HK_LOG_FILE

Type: path · Default: $HK_STATE_DIR/hk.log

Log file location. Example: HK_LOG_FILE=/tmp/hk.log hk check.

HK_LOG_FILE_LEVEL

Type: log level · Default: the environment’s log level

Choose a separate verbosity for file logs. Example: HK_LOG_FILE_LEVEL=trace hk check.

HK_MISE

Type: boolean · Default: false

Make hk install use mise x in hook launchers and make hk init create a starter mise.toml when absent. Reinstall hooks to update an existing launcher. See mise integration. Steps also receive the mise environment for their working directory; explicit step environment values take precedence. See per-directory environments.

HK_OUTPUT_FILE

Type: path Default: ~/.local/state/hk/output.log

The file where hk writes the complete output of a failed command. An empty value uses the default location.

HK_PKL_BACKEND

Type: pklr · Default: unset

hk v2 always uses its built-in pklr evaluator. The value pklr is accepted as a compatibility no-op; pkl and other values fail with a link to the v2 migration guide.

HK_PKL_CACHE_DIR

Type: path Default: the platform cache directory with pklr appended (~/.cache/pklr on Linux, ~/Library/Caches/pklr on macOS, and %LOCALAPPDATA%\pklr on Windows). Falls back to ~/.cache/pklr when the platform cache directory is unavailable.

The directory used by the built-in pklr evaluator to persist downloaded Pkl packages. Packages in this cache can be reused after hk's resolved configuration cache is invalidated, including in offline mode.

This variable is read directly from the environment before hk.pkl is evaluated, so it cannot be configured in hk.pkl.

HK_PKL_CA_CERTIFICATES

Type: path · Default: unset

A path to a PEM bundle containing CA certificates trusted by the built-in pklr evaluator, in addition to the system roots, when it downloads Pkl packages. This is useful behind an SSL-intercepting proxy. This must be set before configuration is evaluated.

HK_PKL_EMBEDDED

Type: bool Default: true

hk embeds the Pkl package for its own version and seeds HK_PKL_CACHE_DIR with it before evaluating hk.pkl. A config pinning the running hk version therefore evaluates without a network request, even on a cold cache. A config pinning any other version is downloaded as usual.

Set to 0 to disable seeding. The package is then resolved from HK_PKL_CACHE_DIR, falling back to the network unless HK_PKL_OFFLINE is set, in which case a package missing from the cache fails.

This variable is read directly from the environment before hk.pkl is evaluated, so it cannot be configured in hk.pkl.

HK_PKL_HTTP_REWRITE

Type: string · Default: unset

URL rewrite rules used by the built-in pklr evaluator. A rule has the form https://source.example/=https://mirror.example/: a URL that starts with the left side is fetched from the right side instead. Separate several rules with commas; when more than one matches, the longest source prefix wins. A rule with no = is ignored with a warning. The variable must be set before evaluation.

Package downloads are rewritten as the https://host/path/name@version.zip URL, so one rule can redirect a whole package host to a mirror. See share configuration across repositories, including how to supply credentials.

HK_PKL_OFFLINE

Type: bool Default: false

Disables network access in the built-in pklr evaluator. Package imports already present in HK_PKL_CACHE_DIR, along with the package embedded for the running version (see HK_PKL_EMBEDDED), remain available; a missing package fails immediately with its URL and cache location.

This variable is read directly from the environment before hk.pkl is evaluated, so it cannot be configured in hk.pkl.

HTTP_PROXY, HTTPS_PROXY, NO_PROXY

Type: URL, URL, host list · Default: unset

The built-in pklr evaluator sends package and module downloads through a proxy. It uses the first of http_proxy, HTTP_PROXY, https_proxy, and HTTPS_PROXY that is set and nonempty, for every download whatever its scheme. no_proxy or NO_PROXY lists hosts that bypass it. A proxy that intercepts TLS also needs HK_PKL_CA_CERTIFICATES.

HK_PROFILE

Type: comma-separated profile names · Default: empty

Enable profiles such as slow or types. Prefix a name with ! to disable it. HK_PROFILES is also accepted. A step requires all of its positive profiles. Example: HK_PROFILE=ci,slow hk check --all.

HK_SKIP_HOOK

Type: comma-separated hook names · Default: empty

Skip entire hooks, for example HK_SKIP_HOOK=pre-push git push. HK_SKIP_HOOKS is also accepted. Skip lists combine with Git and Pkl configuration.

HK_SKIP_STEPS

Type: comma-separated step names · Default: empty

Skip named steps in any hook, for example HK_SKIP_STEPS=eslint hk check. HK_SKIP_STEP is also accepted. Skip lists combine across configuration sources.

HK_STAGE

Type: boolean · Default: the hook’s staging setting

Override automatic staging of fixes. Set HK_STAGE=0 to leave fixes for review. See reviewing fixes.

HK_STASH

Type: git, patch-file, or none · Default: the hook’s setting, otherwise none

Override how unstaged work is saved before a hook. git enables stashing; patch-file currently uses the same Git implementation; none leaves unstaged work in place. Boolean true/1 and false/0 are also accepted. A hook defaults to none unless it sets stash; the pre-commit hook that hk builds from top-level steps (the setup hk init creates) uses git. See stashing.

HK_STASH_BACKUP_COUNT

Type: nonnegative integer · Default: 20

Number of backup patches to retain per repository under $HK_STATE_DIR/patches/. Set to 0 to disable patch backups.

HK_STASH_LOCK_TIMEOUT

Type: nonnegative integer (seconds) · Default: 300

How long to wait for another hk process in the same repository to finish stashing, using the hk-stash.lock file in the common git directory that linked worktrees share. On timeout hk fails and names the lock file. Set to 0 to fail at once instead of waiting. Also settable with git config hk.stashLockTimeout.

HK_STASH_UNTRACKED

Type: boolean · Default: true

Include untracked files when stashing. Setting this to false also skips untracked-file discovery entirely: those files will not appear in status-based reports or normal hk check --all selection. This can reduce scan time for very large worktrees, such as dotfiles repositories rooted at the home directory.

HK_STATE_DIR

Type: path · Default: platform state directory plus hk

Directory for logs and stash backup patches. It typically resolves to ~/.local/state/hk on Linux; hk also uses that fallback on platforms without a state-directory convention.

HK_SUMMARY_TEXT

Type: boolean · Default: false

In plain-text mode, hk prints summaries for failed steps by default. Set to true to include successful-step summaries too; their output normally streams during execution.

HK_TERMINAL_PROGRESS

Type: boolean · Default: true

Send progress updates through OSC sequences to compatible terminals. Disable this if the terminal renders those updates incorrectly.

HK_TIMING_JSON

Type: path · Default: unset

Write total and per-step wall time as JSON after a hook finishes. Example: HK_TIMING_JSON=hk-timing.json hk check --all. See timing reports.

HK_TRACE

Type: 1, true, or json · Default: off

Enable text tracing with HK_TRACE=1, or JSON trace events with HK_TRACE=json. Text goes to standard error; JSON events go to standard output. Other values, including off, disable tracing; text is not an alias for 1. See tracing.

HK_WALK_IGNORE

Type: boolean · Default: true

Respect .gitignore and other ignore files during directory walks. This affects discovery; other file filters and step exclusions still apply.

HK_WARNINGS

Type: comma-separated warning tags · Default: empty

Enable opt-in warning categories, currently including missing-profiles. In Pkl, use warnings = List("missing-profiles").

HK_REPORT_JSON

hk sets this variable for a hook’s report command. It contains the same timing data that HK_TIMING_JSON writes to a file. It is an output supplied to the report command, not a setting for users to configure.

report = "node scripts/report-timings.js"

The script can read process.env.HK_REPORT_JSON. See timing reports for the JSON shape.