hk.usage.kdl

// @generated by usage-derive metadata
min_usage_version "4.0"
name hk
bin hk
version "1.58.1"
unknown_flags error
subcommand_required #true
flagset hook-options {
    flag "-a --all" help="Select all tracked and eligible untracked files, then apply step filters" {
        conflicts --staged --unstaged
    }
    flag "-c --check" help="Run check command instead of fix command" overrides=--fix
    flag "-e --exclude" help="Exclude files that otherwise would have been selected" var=#true {
        arg <EXCLUDE>
    }
    flag "-f --fix" help="Run fix commands instead of check commands for this invocation" overrides=--check
    flag "-g --glob" help="Run on files that match these glob patterns" var=#true {
        arg <GLOB>
    }
    flag "-J --json" help="Output the plan as JSON when combined with --plan or --why"
    flag "-P --plan" help="Print the plan instead of running the hook"
    flag "-S --step" help="Run only specific step(s)" var=#true {
        arg <STEP>
    }
    flag "-W --why" help="Show detailed reasons for inclusion/exclusion. Pass a step name to focus on one step, or omit the value to show reasons for all steps. Implies --plan." value_optional=#true default_missing="" {
        arg "[STEP]" required=#false
    }
    flag --fail-fast help="Abort on first failure" overrides=--no-fail-fast
    flag --files0-from help="Read the exact file list from a NUL-delimited file, or from stdin with `-` (except hooks that reserve stdin)" {
        conflicts --all --from-ref --glob --pr --staged --to-ref --unstaged
        arg <PATH>
    }
    flag --format help="Select human or machine-readable execution output" {
        arg <FORMAT> {
            choices {
                choice human
                choice json
                choice jsonl
            }
        }
    }
    flag --from-hook help="Invoked by an installed git hook — gracefully exit 0 when no hk.pkl is present or the event isn't defined. Set automatically by `hk install`." hide=#true
    flag --from-ref help="Select files changed since this reference; optionally pair with --to-ref" {
        arg <FROM_REF>
    }
    flag --no-fail-fast help="Continue on failures (opposite of --fail-fast)" overrides=--fail-fast
    flag --no-stage help="Disable auto-staging of fixed files" overrides=--stage
    flag --pr help="Check only files changed in the current PR/branch (shortcut for --from-ref DEFAULT_BRANCH --to-ref HEAD)" {
        conflicts --all --from-ref --glob --to-ref
    }
    flag --safe help="Reject commands with unknown or destructive effects before execution"
    flag --sarif help="Write normalized diagnostics as SARIF" {
        arg <PATH>
    }
    flag --skip-step help="Skip specific step(s)" var=#true {
        arg <STEP>
    }
    flag --stage help="Enable auto-staging of fixed files" overrides=--no-stage
    flag --staged help="Run on staged files only without stashing unstaged changes" {
        conflicts --all --from-ref --glob --pr --stash --to-ref --unstaged
    }
    flag --stash help="Stash method to use for git hooks" {
        arg <STASH> {
            choices git patch-file none
        }
    }
    flag --stats help="Display statistics about files matching each step"
    flag --to-ref help="End reference for comparison with --from-ref" {
        arg <TO_REF>
    }
    flag --unstaged help="Run on unstaged and untracked files only (excludes staged files), without stashing. Useful for linting files an agent just changed." {
        conflicts --all --from-ref --glob --pr --stash --to-ref --staged
    }
}
flag --cd help="Run as if hk was started in this directory" global=#true {
    arg <DIRECTORY>
}
flag --format help="Select human or machine-readable execution output" default=human {
    arg <FORMAT> {
        choices {
            choice human
            choice json
            choice jsonl
        }
    }
}
flag --hkrc help="Path to user configuration file (deprecated: use ~/.config/hk/config.pkl or hk.local.pkl)" global=#true hide=#true {
    arg <PATH>
}
flag "-j --jobs" help="Number of jobs to run in parallel" global=#true {
    arg <JOBS>
}
flag "-p --profile" help="Profiles to enable or disable. Prefix a profile with ! to disable it, e.g. --profile slow --profile !fast" global=#true var=#true {
    arg <PROFILE>
}
flag "-s --slow" help="Shorthand for --profile=slow" global=#true
flag "-v --verbose" help="Enable verbose (debug) output. Pass twice for trace output" global=#true count=#true var=#true {
    overrides --quiet --silent
}
flag "-n --no-progress" help="Disable progress output" global=#true
flag "-q --quiet" help="Suppress non-essential output (info messages, progress indicators). Failed-step diagnostics are still shown" global=#true {
    overrides --verbose --silent
}
flag --silent help="Suppress all output except errors, including warnings" global=#true {
    overrides --quiet --verbose
}
flag --trace help="Enable tracing spans and performance diagnostics" global=#true
flag --json help="Output in JSON format" global=#true
flag "-h --help" help="Print help" action=help builtin=#true
flag "-V --version" help="Print version" action=version builtin=#true
complete directory type=dir
cmd agent help="Generate integration snippets for coding agents" effect=read subcommand_required=#true {
    flag "-h --help" help="Print help" action=help builtin=#true
    cmd hooks help="Print a hook configuration for an agent or editor" effect=read {
        flag --target help="Agent or editor to generate the hook configuration for" required=#true {
            arg <TARGET> {
                choices {
                    choice codex
                    choice claude-code
                    choice vscode
                }
            }
        }
        flag "-h --help" help="Print help" action=help builtin=#true
    }
    cmd instructions help="Print project instructions for a coding agent" effect=read {
        flag --target help="Agent to generate the instructions for" required=#true {
            arg <TARGET> {
                choices {
                    choice codex
                    choice claude-code
                    choice generic
                }
            }
        }
        flag "-h --help" help="Print help" action=help builtin=#true
    }
    cmd mcp help="Print an MCP server configuration" effect=read {
        flag --target help="MCP host to generate the server configuration for" required=#true {
            arg <TARGET> {
                choices {
                    choice codex
                    choice claude-desktop
                    choice claude-code
                    choice vscode
                }
            }
        }
        flag "-h --help" help="Print help" action=help builtin=#true
    }
}
cmd builtins help="List all available builtin linters" effect=read {
    flag "-h --help" help="Print help" action=help builtin=#true
}
cmd cache help="Manage hk internal cache" hide=#true effect=read subcommand_required=#true {
    flag "-h --help" help="Print help" action=help builtin=#true
    cmd clear help="Clear the cache directory" effect=write {
        flag "-h --help" help="Print help" action=help builtin=#true
    }
}
cmd check help="Run the check hook" {
    alias c
    long_help #"""
Run the check hook

Runs each step's check command, which by convention only reports problems. If the `check` hook sets `fix = true` in `hk.pkl`, or `--fix` is passed, hk runs fix commands instead and can modify and stage files.
"""#
    use hook-options
    flag "-h --help" help="Print help" action=help builtin=#true
    arg "[FILES]..." help="Run on specific files" {
        conflicts --all --files0-from --pr --staged --unstaged
    }
    complete files type=path
    complete exclude type=path
    complete glob type=path
    complete path type=path
}
cmd completion help="Generate shell completion scripts" effect=read {
    flag --install help="Install the script where this shell looks for it, instead of printing it" effect=write {
        long_help #"""
Install the script where this shell looks for it, instead of printing it

Writes the script file and nothing else: no shell rc file and no PowerShell profile is edited. Where a shell needs a one-time line of its own — zsh's `fpath+=`, PowerShell's dot-source — it is printed for you to add.
"""#
    }
    flag --force help="Replace a file at the target path that hk did not write" effect=write requires=--install
    flag "-h --help" help="Print help" action=help builtin=#true
    arg <SHELL> help="The shell to generate completion for"
}
cmd config help="Inspect hk's configuration" effect=read {
    alias cfg
    long_help #"""
Inspect hk's configuration

View hk's effective configuration and where each value comes from. Configuration is merged from multiple sources in precedence order: CLI flags > Environment variables > Git config (local) > Git config (global) > Project config (hk.pkl) > User config (~/.config/hk/config.pkl) > Built-in defaults.
"""#
    flag "-h --help" help="Print help" action=help builtin=#true
    cmd dump help="Print the effective runtime settings" effect=read {
        long_help #"""
Print the effective runtime settings

Shows the merged configuration from all sources, including CLI flags, environment variables, git config, project config, and user config.
"""#
        flag --format help="Output format" default=json {
            arg <FORMAT> {
                choices json toml
            }
        }
        flag "-h --help" help="Print help" action=help builtin=#true
    }
    cmd explain help="Explain where a configuration value comes from" effect=read {
        long_help #"""
Explain where a configuration value comes from

Shows the resolved value, the source it came from (cli, env, git, pkl, or defaults), and every layer that could affect it, in precedence order.
"""#
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <KEY> help="Configuration key to explain"
    }
    cmd get help="Get a specific configuration value" effect=read {
        long_help #"""
Get a specific configuration value

Accepts any setting name shown by `hk config dump` (for example fail_fast, exclude, or skip_steps) plus jobs, enabled_profiles, and disabled_profiles.
"""#
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <KEY> help="Configuration key to retrieve"
    }
    cmd sources help="Show the configuration source precedence order" effect=read {
        long_help #"""
Show the configuration source precedence order

Lists every configuration source from highest to lowest precedence.
"""#
        flag "-h --help" help="Print help" action=help builtin=#true
    }
}
cmd fix help="Run the fix hook" {
    alias f
    long_help #"""
Run the fix hook

Runs each step's fix command to modify files in place. Passing `--check`, or setting `HK_CHECK=1` or `HK_FIX=0`, runs each step's check command instead.
"""#
    use hook-options
    flag "-h --help" help="Print help" action=help builtin=#true
    arg "[FILES]..." help="Run on specific files" {
        conflicts --all --files0-from --pr --staged --unstaged
    }
    complete files type=path
    complete exclude type=path
    complete glob type=path
    complete path type=path
}
cmd init help="Generate a new hk.pkl file for a project" effect=write {
    alias generate
    flag "-f --force" help="Overwrite existing hk.pkl file"
    flag "-i --interactive" help="Interactive mode: select linters and hooks manually"
    flag --mise help="Generate a mise.toml file with hk configured" {
        long_help #"""
Generate a mise.toml file with hk configured

Set HK_MISE=1 to make this the default behavior.
"""#
    }
    flag "-h --help" help="Print help" action=help builtin=#true
}
cmd install help="Set up git hooks to run hk." effect=write {
    alias i
    long_help #"""
Set up git hooks to run hk.

The recommended setup is `hk install --global`, which installs hooks once into the user's `~/.gitconfig` so every repository on the machine picks them up automatically. In a project without an `hk.pkl`, the installed hook exits silently — no-op — so it's safe to enable everywhere. Requires Git 2.54+.

Without `--global`, hooks are installed into the current repo only. On Git 2.54+ this uses config-based hooks (`hook.<name>.command`), which keeps `.git/hooks/` untouched and composes cleanly with other hook managers. On older Git it falls back to writing script shims.

If hk is already configured globally (any `hook.hk-*` entry in `~/.gitconfig`), the per-repo install is skipped — and any stale local hooks are cleaned up — so the global install remains the single source of truth and hk doesn't fire twice per event. Pass `--force-local` to install local hooks anyway.
"""#
    flag --force-local help=#"""
Install local hooks even when hk is already configured globally
(any `hook.hk-*` entry in `~/.gitconfig`). By default a per-repo
install is skipped in that case to avoid hk firing twice per
event. Not compatible with `--global`.
"""# conflicts=--global
    flag --global help=#"""
Recommended. Install at user level (~/.gitconfig) so every repo
on this machine gets hk hooks. Requires Git 2.54 or newer. In
repos without an `hk.pkl`, the installed hook is a silent no-op.
"""#
    flag --legacy help=#"""
Force using the legacy `.git/hooks/` script shims instead of Git
2.54+ config-based hooks. Not compatible with `--global`.
"""# conflicts=--global
    flag --mise help=#"""
Run hooks through `mise x` so mise-managed tools are available
without activating mise in the shell.
"""# {
        long_help #"""
Run hooks through `mise x` so mise-managed tools are available
without activating mise in the shell.

Set HK_MISE=1 to make this the default behavior.
"""#
    }
    flag "-h --help" help="Print help" action=help builtin=#true
}
cmd mcp help="Run an MCP server for coding agents over standard input/output" {
    flag --root help="Restrict hk tools to this project root (defaults to the current directory)" {
        arg <PATH>
    }
    flag "-h --help" help="Print help" action=help builtin=#true
    complete path type=dir
}
cmd migrate help="Migrate from other hook managers to hk" effect=read subcommand_required=#true {
    flag "-h --help" help="Print help" action=help builtin=#true
    cmd pre-commit help="Migrate from pre-commit to hk" effect=write {
        flag "-c --config" help="Path to .pre-commit-config.yaml" default=.pre-commit-config.yaml {
            arg <CONFIG>
        }
        flag "-f --force" help="Overwrite existing hk.pkl file"
        flag "-o --output" help="Output path for hk.pkl" default=hk.pkl {
            arg <OUTPUT>
        }
        flag --hk-pkl-root help="Root path for hk pkl files (e.g. \"pkl\" for a local checkout, or a package URL prefix). If set, the generated config uses {root}/Config.pkl and {root}/Builtins.pkl" {
            arg <HK_PKL_ROOT>
        }
        flag "-h --help" help="Print help" action=help builtin=#true
    }
}
cmd run help="Run a hook" arg_required_else_help=#true {
    alias r
    use hook-options
    flag "-h --help" help="Print help" action=help builtin=#true
    arg "[OTHER]" hide=#true
    arg "[FILES]..." help="Run on specific files" {
        conflicts --all --files0-from --pr --staged --unstaged
    }
    complete files type=path
    complete exclude type=path
    complete glob type=path
    complete path type=path
    cmd commit-msg help="Run the commit-msg hook" {
        alias cm
        use hook-options
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <COMMIT_MSG_FILE> help="The path to the file that contains the commit message"
        arg "[FILES]..." help="Run on specific files" {
            conflicts --all --files0-from --pr --staged --unstaged
        }
        complete files type=path
        complete exclude type=path
        complete glob type=path
        complete path type=path
    }
    cmd post-checkout help="Run the post-checkout hook" {
        use hook-options
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <PREV_HEAD> help="SHA of the HEAD before the checkout"
        arg <NEW_HEAD> help="SHA of the new HEAD"
        arg <IS_BRANCH_CHECKOUT> help="Flag indicating whether the checkout was a branch checkout (1) or file checkout (0)"
        arg "[FILES]..." help="Run on specific files" {
            conflicts --all --files0-from --pr --staged --unstaged
        }
        complete files type=path
        complete exclude type=path
        complete glob type=path
        complete path type=path
    }
    cmd post-commit help="Run the post-commit hook" {
        use hook-options
        flag "-h --help" help="Print help" action=help builtin=#true
        arg "[FILES]..." help="Run on specific files" {
            conflicts --all --files0-from --pr --staged --unstaged
        }
        complete files type=path
        complete exclude type=path
        complete glob type=path
        complete path type=path
    }
    cmd post-merge help="Run the post-merge hook" {
        use hook-options
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <IS_SQUASH> help="Flag indicating whether the merge was a squash merge (1) or not (0)"
        arg "[FILES]..." help="Run on specific files" {
            conflicts --all --files0-from --pr --staged --unstaged
        }
        complete files type=path
        complete exclude type=path
        complete glob type=path
        complete path type=path
    }
    cmd post-rewrite help="Run the post-rewrite hook" {
        use hook-options
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <COMMAND> help="The command that triggered the rewrite (\"amend\" or \"rebase\")"
        arg "[FILES]..." help="Run on specific files" {
            conflicts --all --files0-from --pr --staged --unstaged
        }
        complete files type=path
        complete exclude type=path
        complete glob type=path
        complete path type=path
    }
    cmd pre-commit help="Run the pre-commit hook" {
        alias pc
        use hook-options
        flag "-h --help" help="Print help" action=help builtin=#true
        arg "[FILES]..." help="Run on specific files" {
            conflicts --all --files0-from --pr --staged --unstaged
        }
        complete files type=path
        complete exclude type=path
        complete glob type=path
        complete path type=path
    }
    cmd pre-push help="Run the pre-push hook" {
        alias pp
        use hook-options
        flag "-h --help" help="Print help" action=help builtin=#true
        arg "[REMOTE]" help="Remote name"
        arg "[URL]" help="Remote URL"
        arg "[FILES]..." help="Run on specific files" {
            conflicts --all --files0-from --pr --staged --unstaged
        }
        complete files type=path
        complete exclude type=path
        complete glob type=path
        complete path type=path
    }
    cmd pre-rebase help="Run the pre-rebase hook" {
        use hook-options
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <UPSTREAM> help="The upstream from which the series was forked"
        arg "[BRANCH]" help="The branch being rebased (unset when rebasing the current branch)"
        arg "[FILES]..." help="Run on specific files" {
            conflicts --all --files0-from --pr --staged --unstaged
        }
        complete files type=path
        complete exclude type=path
        complete glob type=path
        complete path type=path
    }
    cmd prepare-commit-msg help="Run the prepare-commit-msg hook" {
        alias pcm
        use hook-options
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <COMMIT_MSG_FILE> help="The path to the file that contains the commit message so far"
        arg "[SOURCE]" help="The source of the commit message (e.g., \"message\", \"template\", \"merge\")"
        arg "[SHA]" help="The SHA of the commit being amended (if applicable)"
        arg "[FILES]..." help="Run on specific files" {
            conflicts --all --files0-from --pr --staged --unstaged
        }
        complete files type=path
        complete exclude type=path
        complete glob type=path
        complete path type=path
    }
}
cmd sponsors help="Show the companies sponsoring hk and the jdx.dev open source tools" effect=read {
    flag "-h --help" help="Print help" action=help builtin=#true
}
cmd test help="Run step-defined tests" {
    flag --list help="List tests without running"
    flag --name help="Filter by test name (repeatable)" {
        arg <NAME>... var_min=1
    }
    flag --step help="Filter by step name (repeatable)" {
        arg <STEP>... var_min=1
    }
    flag "-h --help" help="Print help" action=help builtin=#true
}
cmd uninstall help="Remove hk hooks" effect=destructive {
    long_help #"""
Remove hk hooks

Removes hk's hooks from the current git repository, clearing both legacy `.git/hooks/` shims and config-based `hook.*` entries. Pass `--global` to remove them from the user's `~/.gitconfig` instead.
"""#
    flag --global help="Remove hk hooks from the user's global git config (`~/.gitconfig`)."
    flag "-h --help" help="Print help" action=help builtin=#true
}
cmd usage help="Generates a usage spec for the CLI" hide=#true effect=read {
    long_help #"""
Generates a usage spec for the CLI

https://usage.jdx.dev
"""#
    flag "-h --help" help="Print help" action=help builtin=#true
}
cmd util help="Utility commands for file operations" effect=read subcommand_required=#true {
    flag "-h --help" help="Print help" action=help builtin=#true
    cmd check-added-large-files help="Check for large files being added to the repository" effect=read {
        flag --maxkb help="Maximum file size in kilobytes" default="500" {
            arg <MAXKB>
        }
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <FILES>... help="Files to check"
    }
    cmd check-byte-order-marker help="Check for UTF-8 byte order marker (BOM)" effect=read {
        flag "-d --diff" help="Output a diff of the BOM removal instead of the file name"
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <FILES>... help="Files to check"
    }
    cmd check-case-conflict help="Check for case-insensitive filename conflicts" effect=read {
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <FILES>... help="Files to check for case conflicts"
    }
    cmd check-conventional-commit help="Check that a commit message follows the Conventional Commits format" effect=read {
        long_help #"""
Check that a commit message follows the Conventional Commits format

Titles starting with `fixup! `, `squash! `, or `amend! ` (temporary commits created for `git rebase --autosquash`) skip validation.
"""#
        flag --allowed-types help="Comma-separated list of commit types to accept" var=#true default=build,chore,ci,docs,feat,fix,perf,refactor,revert,style,test delimiter=, {
            arg <ALLOWED_TYPES>
        }
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <COMMIT_MSG_FILE> help="Commit message file to check"
    }
    cmd check-executables-have-shebangs help="Check that executable files have shebangs" effect=read {
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <FILES>... help="Files to check"
    }
    cmd check-merge-conflict help="Check for merge conflict markers" effect=read {
        flag --assume-in-merge help="Run the check even when not in a merge"
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <FILES>... help="Files to check"
    }
    cmd check-symlinks help="Check for broken symlinks" effect=read {
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <FILES>... help="Files to check"
    }
    cmd detect-private-key help="Detect private keys in files" effect=read {
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <FILES>... help="Files to check"
    }
    cmd end-of-file-fixer help="Check for and optionally fix missing final newlines" effect=write {
        flag "-d --diff" help="Output a diff of the change. Cannot use with `fix`." conflicts=--fix
        flag "-f --fix" help="Fix files to end with exactly one newline"
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <FILES>... help="Files to check/fix"
    }
    cmd fix-byte-order-marker help="Remove UTF-8 byte order marker (BOM)" effect=write {
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <FILES>... help="Files to remove BOM from"
    }
    cmd fix-smart-quotes help="Replace smart quotes with plain ASCII quotes" effect=write {
        flag --check help="Check for smart quotes without fixing them"
        flag "-d --diff" help="Output a diff of the change (implies `--check`)"
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <FILES>... help="Files to check/fix"
    }
    cmd mixed-line-ending help="Detect and fix mixed line endings" effect=write {
        flag "-d --diff" help="Output a diff of the change. Cannot use with `fix`." conflicts=--fix
        flag "-f --fix" help="Fix mixed line endings by normalizing to LF"
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <FILES>... help="Files to check or fix"
    }
    cmd no-commit-to-branch help="Prevent commits to specific branches" effect=read {
        flag --branch help="Branch names to protect (default: main, master)" var=#true delimiter=, {
            arg <BRANCH>
        }
        flag "-h --help" help="Print help" action=help builtin=#true
    }
    cmd python-check-ast help="Check Python files for valid syntax" effect=read {
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <FILES>... help="Files to check"
    }
    cmd python-debug-statements help="Detect Python debug statements" effect=read {
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <FILES>... help="Files to check"
    }
    cmd trailing-whitespace help="Check for and optionally fix trailing whitespace" effect=write {
        flag "-d --diff" help="Output a diff of the change. Cannot use with `fix`." conflicts=--fix
        flag "-f --fix" help="Fix trailing whitespace by removing it"
        flag "-h --help" help="Print help" action=help builtin=#true
        arg <FILES>... help="Files to check/fix"
    }
}
cmd validate help="Validate the config file" effect=read {
    flag "-h --help" help="Print help" action=help builtin=#true
}
cmd version help="Print the version of hk" effect=read {
    flag "-h --help" help="Print help" action=help builtin=#true
}