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)
--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.
--wheel-scroll-lines <lines>	rows per wheel event: auto or 1-10 Default: auto.
--scroll-off <rows>	rows the current line keeps clear of the viewport edge: 0-40 Default: 5.
--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
--disable-extension <id>	disable one bundled or user extension for this run (repeatable)
--enable-extension <id>	re-enable one extension for this run (repeatable)

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

hunk open

view a complete file or browse a directory

Usage

hunk open [path]

Defaults to the current directory. Reads are lazy and the browser refreshes automatically.

Press i to show hidden and Git-ignored entries. Symlinks are displayed but not followed.

Command-specific options

Option	Description
--theme <theme>	named theme override
--line-numbers	show line numbers
--no-line-numbers	hide line numbers
--sidebar	show the directory tree
--no-sidebar	hide the directory tree
--wrap	wrap long document lines
--no-wrap	keep long document lines on one row
-x, --tab-width <columns>	tab stop width: 1-16

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 status

inspect the current workspace and sibling worktrees

Usage

hunk status [--static | --json]

Terminals open live workspace status; redirects receive one static snapshot.

Enter inspects a row; S/U review staged/working-tree changes; L opens Log; Q returns or quits.

F10 opens menus, T chooses a theme, R refreshes, and W expands other worktrees.

--json emits the versioned status snapshot without paging or terminal color.

Status never fetches or modifies the repository; providers without status report unsupported.

Command-specific options

Option	Description
--mode <mode>	layout mode: auto, split, unified
--cursor-line <style>	current-line marker: row, number, off
--theme <theme>	named theme override
--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.
--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.
--wheel-scroll-lines <lines>	rows per wheel event: auto or 1-10 Default: auto.
--scroll-off <rows>	rows the current line keeps clear of the viewport edge: 0-40 Default: 5.
--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
--disable-extension <id>	disable one bundled or user extension for this run (repeatable)
--enable-extension <id>	re-enable one extension for this run (repeatable)
--vcs <id>	select a VCS status provider
--static	print one snapshot, paging when needed
--json	emit a version 1 JSON snapshot
--color <mode>	color output: auto, always, never

hunk log

browse repository history

Usage

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

A terminal opens the responsive browser; pipes and redirects receive static output.

Use --static to force static output, paging when it exceeds the terminal.

The selected VCS provider defines revision, filtering, and review semantics.

Command-specific options

Option	Description
--all	include history from every provider-visible head
--first-parent	follow only the first parent of merge commits
-n, --max-count <count>	stop after this many commits
--author <pattern>	limit commits by author
--grep <pattern>	limit commits by subject or message
--since <date>	show commits newer than a provider date
--until <date>	show commits older than a provider date
--color <mode>	color output: auto, always, never
--format <format>	static record format: medium or compact
--oneline	alias for static --format compact
--theme <id>	use the same theme as Hunk review
--ascii	use an ASCII graph
--static	print static output, paging when needed
--vcs <id>	select a VCS history provider
--extension <path>	load an extension entry file or directory (repeatable)
--no-extensions	disable user extensions for this run
--disable-extension <id>	disable one bundled or user extension for this run (repeatable)
--enable-extension <id>	re-enable one extension for this run (repeatable)

hunk gh

Review GitHub pull requests, commits, and comparisons. This command is provided by the bundled hunk.gh extension; disable it with --disable-extension hunk.gh or the [extensions] config table.

Usage

hunk gh pr [pull-request] [--repo <owner/repo>] [-- <patch-options...>]
hunk gh commit <commit> [--repo <owner/repo>] [-- <patch-options...>]
hunk gh compare <base>...<head> [--repo <owner/repo>] [-- <patch-options...>]

Command-specific options

Option	Description
--repo <owner/repo>	use an explicit repository instead of the local origin
-- <patch-options...>	pass the remaining options to the hunk patch review

Patch options after -- accept every common review option.

Authentication: GH_TOKEN, then GITHUB_TOKEN; optional for public repositories.

hunk gh pr

Review a GitHub pull request without requiring the gh CLI.

hunk gh pr [pull-request] [--repo <owner/repo>] [-- <patch-options...>]

Pull request forms:

hunk gh pr                            # find the open PR for the current branch
hunk gh pr 123                        # infer owner/repo from the local origin
hunk gh pr 123 --repo modem-dev/hunk  # use an explicit repository
hunk gh pr 'modem-dev/hunk#123'       # name the repository and pull request
hunk gh pr https://github.com/modem-dev/hunk/pull/123

hunk gh commit

Review a GitHub commit without requiring the gh CLI.

hunk gh commit <commit> [--repo <owner/repo>] [-- <patch-options...>]

Commit forms:

hunk gh commit abcdef1                        # infer owner/repo from the local origin
hunk gh commit abcdef1 --repo modem-dev/hunk  # use an explicit repository
hunk gh commit modem-dev/hunk@abcdef1         # name the repository and commit
hunk gh commit https://github.com/modem-dev/hunk/commit/abcdef1

hunk gh compare

Review the changes between two GitHub branches, tags, or commits.

hunk gh compare <base>...<head> [--repo <owner/repo>] [-- <patch-options...>]

Compare forms:

hunk gh compare main...feature  # infer owner/repo from the local origin
hunk gh compare v0.20.0...v0.21.0 --repo modem-dev/hunk

Use three dots exactly. Pass Hunk patch options after --.

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 completion

print a shell completion script

Usage

hunk completion <bash|zsh>

Load it into the current shell with source <(hunk completion zsh) or eval "$(hunk completion bash)", and add that line to your shell startup file to keep it.

For Zsh, initialize completion with autoload -Uz compinit; compinit before loading the script, unless your shell framework already does so.

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 skill show

print a bundled Hunk skill

Usage

hunk skill show [name]

Prints the full SKILL.md shipped with the installed Hunk version. Pointer skills installed with npx skills add modem-dev/hunk run this command to load their instructions, so the text always matches the installed CLI.

hunk extension install

install a shared extension from Git or npm

Usage

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

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

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