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, unified
--cursor-line <style>	current-line marker: row, number, off
--theme <theme>	named theme override
--agent-context <path>	JSON sidecar with agent rationale
--pager	use pager-style chrome
--experimental	enable experimental features (currently STML agent-note markup)
--fast	experimentally offload eligible syntax highlighting
--line-numbers	show line numbers
--no-line-numbers	hide line numbers
-x, --tab-width <columns>	tab stop width: 1-16 Default: 4.
--file-gap <rows>	file separator rows, including the ─ rule: 0-8 Default: 1.
--hunk-gap <rows>	blank rows before each later hunk: 0-8 Default: 0.
--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
--sidebar	show files pane
--no-sidebar	hide files pane
--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 <from> <to> [-- <pathspec...>]
hunk diff --staged [-- <pathspec...>]
hunk diff --files <left> <right>

Two positional arguments always name revision endpoints, even when matching files exist on disk.

Use --files <left> <right> for concrete-file comparison; this replaces the former filesystem-existence disambiguation.

Command-specific options

Option	Description
--files <paths...>	compare exactly two concrete files: --files <left> <right>
--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 a bundled Hunk skill path

Usage

hunk skill path [name]

hunk extension install

install a shared extension from a git repository

Usage

hunk extension install <owner>/<repo>[@ref]
hunk extension install git:<host>/<path>[@ref]
hunk extension install <git-url or local path>[@ref]

Aliases: hunk ext install.

Command-specific options

Option	Description
--yes	skip the confirmation prompt (required without a TTY)

hunk extension list

list extensions installed with hunk extension install

Usage

hunk extension list

Aliases: hunk ext list.

hunk extension update

re-clone managed extension installs from their recorded sources

Usage

hunk extension update [name]

Aliases: hunk ext update.

hunk extension remove

remove one managed extension install

Usage

hunk extension remove <name>

Aliases: hunk ext remove.

hunk update

update Hunk with the package manager that installed it

Usage

hunk update [version]
hunk update --check
hunk update --method <npm|brew|curl>

Command-specific options

Option	Description
--method <method>	install method instead of the detected one: npm, brew, curl
--check	report the installed and available versions without installing

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 daemon status

report the running session daemon's build, uptime, and attached windows

Usage

hunk daemon status [--json]

After a Hunk upgrade, a daemon from the previous build keeps running while any window holds it open, and windows or hunk session commands from the new build cannot attach to it. status shows which build the daemon is, how it compares to this CLI, and which windows are attached; attached windows are marked (older build) when they could not reconnect to a daemon started from this CLI.

A daemon from a Hunk release before this command cannot report its build; status then shows what its launch metadata recorded.

Command-specific options

Option	Description
--json	print the status as JSON

hunk daemon restart

stop the running session daemon and start one from this Hunk build

Usage

hunk daemon restart [--yes] [--json]

Prints the same summary as status, asks for confirmation, stops the daemon, and starts a replacement from this CLI's binary. Windows from this build that could not attach register with the replacement on their own; windows from the old build are disconnected and must be relaunched, which loses their in-window notes. The daemon is never replaced automatically.

A daemon from a Hunk release before this command cannot be asked to stop; restart then asks separately before sending SIGTERM to the pid its launch metadata recorded.

Command-specific options

Option	Description
--yes	skip the confirmation prompts (required when stdin is not a terminal)
--json	print the result as JSON

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>) --comment <id> [--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
--comment <id>	jump to the live comment with this id
--next-comment	jump to the next annotated hunk
--prev-comment	jump to the previous annotated hunk
--json	emit structured JSON

Positionals: [sessionId].

Constraints: for --file navigation, 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 . --comment comment-1
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>) (--reply-to <note-id> | --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
--reply-to <note-id>	reply to an existing note at its anchor
--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].

Examples:

hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording"
hunk session comment add --repo . --reply-to user:123 --summary "Addressed in the latest revision"

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"
      },
      {
        "replyTo": "user:123",
        "summary": "Addressed in the latest revision"
      }
    ]
  }
Each item is either a reply with `replyTo`, or a root with `filePath` and one target.

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].

hunk session highlight add

paint one attention mark inside a diff line

hunk session highlight add (<session-id> | --repo <path>) --file <path> (--old-line <n> | --new-line <n>) --start <n> --end <n> [--tone <tone>] [--focus] [--json]

Option	Description
--file <path>	diff file path as shown by Hunk Required.
--start <n>	0-based inclusive start offset into the line's text (UTF-16 code units) Required.
--end <n>	exclusive end offset; must be greater than --start 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
--tone <tone>	mark tone: match, current, info, warning, error, dim (default match)
--focus	add the mark and land the viewport on its line
--json	emit structured JSON

Positionals: [sessionId].

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

Examples:

hunk session highlight add --repo . --file src/App.tsx --new-line 42 --start 6 --end 19
hunk session highlight add --repo . --file src/App.tsx --new-line 42 --start 6 --end 19 --tone warning --focus

hunk session highlight clear

clear agent attention marks

hunk session highlight clear (<session-id> | --repo <path>) [--file <path>] [--json]

Option	Description
--repo <path>	target the live session whose repo root matches this path
--file <path>	clear only one diff file's marks
--json	emit structured JSON

Positionals: [sessionId].

Examples:

hunk session highlight clear --repo .