CLI reference

This reference is generated from the command metadata used by Hunk itself. Run hunk --help or hunk <command> --help to inspect the installed version.

Global options

Option	Description
-h, --help	Show top-level or command-specific help.
-v, --version	Print the installed Hunk version.

Common review options

Option	Description
--mode <mode>	layout mode: auto, split, stack
--theme <theme>	named theme override
--agent-context <path>	JSON sidecar with agent rationale
--pager	use pager-style chrome and controls
--experimental	enable experimental features (currently STML agent-note markup)
--line-numbers	show line numbers
--no-line-numbers	hide line numbers
-x, --tab-width <columns>	tab stop width: 1-16 Default: 4.
--wrap	wrap long diff lines
--no-wrap	truncate long diff lines to one row
--hunk-headers	show hunk metadata rows
--no-hunk-headers	hide hunk metadata rows
--agent-notes	show agent notes by default
--no-agent-notes	hide agent notes by default
--transparent-bg	let terminal background show through Hunk surfaces
--no-transparent-bg	paint Hunk surfaces with the active theme
--extension <path>	load an extension entry file or directory (repeatable)
--no-extensions	disable user extensions for this run

--experimental may also be placed before the review command, as in hunk --experimental diff.

hunk diff

review diffs or compare two concrete files

Usage

hunk diff [target] [-- <pathspec...>]
hunk diff --staged [-- <pathspec...>]
hunk diff <left> <right>

Command-specific options

Option	Description
--staged	show staged changes instead of the working tree
--cached	alias for --staged
--exclude-untracked	exclude untracked files from working tree reviews
--no-exclude-untracked	include untracked files in working tree reviews Compatibility inverse; omitted from --help.

Also accepts --watch: auto-reload when the current diff input changes.

Also accepts every common review option.

hunk show

review the last commit or a given ref

Usage

hunk show [target] [-- <pathspec...>]

Also accepts --watch: auto-reload when the current diff input changes.

Also accepts every common review option.

hunk stash show

review a stash entry as a full Hunk changeset

Usage

hunk stash show [ref]

Also accepts --watch: auto-reload when the current diff input changes.

Also accepts every common review option.

hunk patch

review a patch file, or read a patch from stdin

Usage

hunk patch [file]

Also accepts --watch: auto-reload when the current diff input changes.

Also accepts every common review option.

hunk pager

general Git pager wrapper with diff detection

Usage

hunk pager

Also accepts every common review option.

hunk difftool

review Git difftool file pairs

Usage

hunk difftool <left> <right> [path]

Also accepts --watch: auto-reload when the current diff input changes.

Also accepts every common review option.

hunk markup render

preview experimental STML markup as terminal text

Usage

hunk markup render (<file> | -) [options]

Command-specific options

Option	Description
--width <n>	layout width in columns Default: 56.
--color <mode>	auto, always, or never Default: auto.
--theme <id>	hunk theme used to resolve colors
--json	emit structured JSON

hunk markup guide

print the experimental STML authoring guide

Usage

hunk markup guide

hunk skill path

print the bundled Hunk review skill path

Usage

hunk skill path

hunk daemon serve

run the local Hunk session daemon and websocket session broker

Usage

hunk daemon serve

Aliases: hunk mcp serve.

Environment

Variable	Purpose
HUNK_MCP_HOST	Bind host; defaults to loopback 127.0.0.1.
HUNK_MCP_PORT	Bind port; defaults to 47657.
HUNK_MCP_UNSAFE_ALLOW_REMOTE	Set to 1 to allow unsafe non-loopback binding.

hunk session

Inspect and control live Hunk review sessions through the loopback daemon. Select a session by id or with --repo <path> where shown.

hunk session list

list live Hunk sessions

hunk session list [--json]

Option	Description
--json	emit structured JSON

hunk session get

show one live Hunk session

hunk session get (<session-id> | --repo <path>) [--json]

Option	Description
--repo <path>	target the live session whose repo root matches this path
--json	emit structured JSON

Positionals: [sessionId].

hunk session context

show the selected file and hunk for one live Hunk session

hunk session context (<session-id> | --repo <path>) [--json]

Option	Description
--repo <path>	target the live session whose repo root matches this path
--json	emit structured JSON

Positionals: [sessionId].

hunk session review

export the live review model for one Hunk session

hunk session review (<session-id> | --repo <path>) [--include-patch] [--include-notes] [--json]

Option	Description
--repo <path>	target the live session whose repo root matches this path
--include-patch	include raw unified diff text for each file in review output
--include-notes	include live review notes in review output
--json	emit structured JSON

Positionals: [sessionId].

hunk session navigate

move a live Hunk session to one diff hunk

hunk session navigate (<session-id> | --repo <path>) --file <path> (--hunk <n> | --old-line <n> | --new-line <n>) [--json]
hunk session navigate (<session-id> | --repo <path>) (--next-comment | --prev-comment) [--json]

Option	Description
--file <path>	diff file path as shown by Hunk
--repo <path>	target the live session whose repo root matches this path
--hunk <n>	1-based hunk number within the file
--old-line <n>	1-based line number on the old side
--new-line <n>	1-based line number on the new side
--next-comment	jump to the next annotated hunk
--prev-comment	jump to the previous annotated hunk
--json	emit structured JSON

Positionals: [sessionId].

Constraints: exactly one of --hunk <n>, --old-line <n>, --new-line <n>; at most one of --next-comment, --prev-comment.

Examples:

hunk session navigate --repo . --file src/App.tsx --hunk 2
hunk session navigate --repo . --file src/App.tsx --new-line 372
hunk session navigate --repo . --file src/App.tsx --old-line 355
hunk session navigate --repo . --next-comment
hunk session navigate --repo . --prev-comment

hunk session reload

replace the contents of one live Hunk session

hunk session reload (<session-id> | --repo <path> | --session-path <path>) [--source <path>] [--json] -- diff [ref] [-- <pathspec...>]
hunk session reload (<session-id> | --repo <path> | --session-path <path>) [--source <path>] [--json] -- show [ref] [-- <pathspec...>]

Option	Description
--repo <path>	target the live session whose repo root matches this path
--session-path <path>	target a live session rooted at a different path
--source <path>	load the diff from this directory instead of the session's own
--json	emit structured JSON

Positionals: [sessionId].

Examples:

hunk session reload --repo . -- diff
hunk session reload --repo . -- diff main...feature -- src/ui
hunk session reload --repo . -- show HEAD~1
hunk session reload --repo . -- show HEAD~1 -- README.md
hunk session reload --repo /path/to/worktree -- diff
hunk session reload --session-path /path/to/live-window --source /path/to/other-checkout -- diff

hunk session comment add

attach one live inline review note

hunk session comment add (<session-id> | --repo <path>) --file <path> (--old-line <n> | --new-line <n>) --summary <text> [--rationale <text>] [--author <name>] [--markup <stml>] [--focus] [--json]

Option	Description
--file <path>	diff file path as shown by Hunk Required.
--summary <text>	short review note Required.
--repo <path>	target the live session whose repo root matches this path
--old-line <n>	1-based line number on the old side
--new-line <n>	1-based line number on the new side
--rationale <text>	optional longer explanation
--markup <stml>	experimental STML body (target session must opt in)
--author <name>	optional author label
--focus	add the note and focus the viewport on it
--json	emit structured JSON

Positionals: [sessionId].

Constraints: exactly one of --old-line <n>, --new-line <n>.

Examples:

hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording"

hunk session comment apply

apply many live inline review notes from stdin JSON

hunk session comment apply (<session-id> | --repo <path>) --stdin [--focus] [--json]

Option	Description
--repo <path>	target the live session whose repo root matches this path
--stdin	read the comment batch from stdin as JSON
--focus	apply the batch and focus the first note
--json	emit structured JSON

Positionals: [sessionId].

Examples:

printf '%s\n' '{"comments":[{"filePath":"README.md","newLine":103,"summary":"Tighten this wording"}]}' | hunk session comment apply --repo . --stdin

Additional input contract:

Stdin JSON shape:
  {
    "comments": [
      {
        "filePath": "README.md",
        "hunk": 2,
        "summary": "Explain this hunk",
        "rationale": "Optional detail",
        "author": "Pi"
      }
    ]
  }

hunk session comment list

list live inline review notes

hunk session comment list (<session-id> | --repo <path>) [--file <path>] [--type <live|all|ai|agent|user>] [--json]

Option	Description
--repo <path>	target the live session whose repo root matches this path
--file <path>	filter comments to one diff file
--type <type>	filter to live, all, ai, agent, or user comments
--json	emit structured JSON

Positionals: [sessionId].

hunk session comment rm

remove one inline review note

hunk session comment rm (<session-id> | --repo <path>) <comment-id> [--json]

Option	Description
--repo <path>	target the live session whose repo root matches this path
--json	emit structured JSON

Positionals: [targets...] — <session-id> <comment-id>, or <comment-id> with --repo.

hunk session comment clear

clear inline review notes

hunk session comment clear (<session-id> | --repo <path>) [--file <path>] [--include-user|--all] --yes [--json]

Option	Description
--repo <path>	target the live session whose repo root matches this path
--file <path>	clear only one diff file's comments
--include-user	also clear human notes created with the TUI c action
--all	clear both live agent comments and human user notes
--yes	confirm destructive comment clearing
--json	emit structured JSON

Positionals: [sessionId].