---
title: CLI reference
description: Exhaustive generated reference for Hunk commands, options, and
  live-session controls.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

<!-- GENERATED by `bun run generate:docs`. Edit the runtime metadata sources imported by scripts/generate-docs.ts instead. -->

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

```bash
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](#common-review-options).

## `hunk show`

review the last commit or a given ref

### Usage

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

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

Also accepts every [common review option](#common-review-options).

## `hunk stash show`

review a stash entry as a full Hunk changeset

### Usage

```bash
hunk stash show [ref]
```

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

Also accepts every [common review option](#common-review-options).

## `hunk patch`

review a patch file, or read a patch from stdin

### Usage

```bash
hunk patch [file]
```

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

Also accepts every [common review option](#common-review-options).

## `hunk pager`

general Git pager wrapper with diff detection

### Usage

```bash
hunk pager
```

Also accepts every [common review option](#common-review-options).

## `hunk difftool`

review Git difftool file pairs

### Usage

```bash
hunk difftool <left> <right> [path]
```

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

Also accepts every [common review option](#common-review-options).

## `hunk markup render`

preview experimental STML markup as terminal text

### Usage

```bash
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

```bash
hunk markup guide
```

## `hunk skill path`

print a bundled Hunk skill path

### Usage

```bash
hunk skill path [name]
```

## `hunk extension install`

install a shared extension from a git repository

### Usage

```bash
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

```bash
hunk extension list
```

**Aliases:** `hunk ext list`.

## `hunk extension update`

re-clone managed extension installs from their recorded sources

### Usage

```bash
hunk extension update [name]
```

**Aliases:** `hunk ext update`.

## `hunk extension remove`

remove one managed extension install

### Usage

```bash
hunk extension remove <name>
```

**Aliases:** `hunk ext remove`.

## `hunk update`

update Hunk with the package manager that installed it

### Usage

```bash
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

```bash
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

```bash
hunk session list [--json]
```

| Option   | Description          |
| -------- | -------------------- |
| `--json` | emit structured JSON |

### `hunk session get`

show one live Hunk session

```bash
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

```bash
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

```bash
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

```bash
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:**

```bash
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

```bash
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:**

```bash
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

```bash
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:**

```bash
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

```bash
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:**

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

**Additional input contract:**

```text
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

```bash
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

```bash
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...]` — &lt;session-id&gt; &lt;comment-id&gt;, or &lt;comment-id&gt; with --repo.

### `hunk session comment clear`

clear inline review notes

```bash
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

```bash
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 (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:**

```bash
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

```bash
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:**

```bash
hunk session highlight clear --repo .
```