---
title: "hk check"
description: "Check a full repository or inspect one step before running it."
---

<!-- @generated by usage-cli from usage spec -->

# `hk check`

- **Usage:** `hk check [FLAGS] [FILES]…`
- **Aliases:** `c`

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.

## Arguments

- **`[FILES]…`** — Run on specific files

## Flags

- **`-a --all`** — Select all tracked and eligible untracked files, then apply step filters
- **`-c --check`** — Run check command instead of fix command
- **`-e --exclude <EXCLUDE>`** — Exclude files that otherwise would have been selected
- **`-f --fix`** — Run fix commands instead of check commands for this invocation
- **`-g --glob <GLOB>`** — Run on files that match these glob patterns
- **`-J --json`** — Output the plan as JSON when combined with --plan or --why
- **`-P --plan`** — Print the plan instead of running the hook
- **`-S --step <STEP>`** — Run only specific step(s)
- **`-W --why [STEP]`** — 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.
- **`--fail-fast`** — Abort on first failure
- **`--files0-from <PATH>`** — Read the exact file list from a NUL-delimited file, or from stdin with `-` (except hooks that reserve stdin)
- **`--format <FORMAT>`** — Select human or machine-readable execution output

  **Choices:** `human`, `json`, `jsonl`

- **`--from-ref <FROM_REF>`** — Select files changed since this reference; optionally pair with --to-ref
- **`--junit-xml <PATH>`** — Write step results as a JUnit XML report
- **`--no-fail-fast`** — Continue on failures (opposite of --fail-fast)
- **`--no-stage`** — Disable auto-staging of fixed files
- **`--pr`** — Check only files changed in the current PR/branch (shortcut for --from-ref DEFAULT_BRANCH --to-ref HEAD)
- **`--safe`** — Reject commands with unknown or destructive effects before execution
- **`--sarif <PATH>`** — Write normalized diagnostics as SARIF
- **`--skip-step <STEP>`** — Skip specific step(s)
- **`--stage`** — Enable auto-staging of fixed files
- **`--staged`** — Run on staged files only without stashing unstaged changes
- **`--stash <STASH>`** — Stash method to use for git hooks

  **Choices:** `git`, `patch-file`, `none`

- **`--stats`** — Display statistics about files matching each step
- **`--to-ref <TO_REF>`** — End reference for comparison with --from-ref
- **`--unstaged`** — Run on unstaged and untracked files only (excludes staged files), without stashing. Useful for linting files an agent just changed.
- **`-h --help`** — Print help

<!-- hk documentation examples -->

## Examples

Check a full repository or inspect one step before running it.

```sh
hk check --all
hk check --step eslint
hk check --why eslint
hk check --plan --json
```

## Learn more

[Getting started](/getting_started) · [Troubleshooting](/logging) · [All commands](/cli/)