add --mouse cli option to enable mouse reporting

.claude/docs/cli.md

@@ -29,6 +29,7 @@
 | `--print-query` | bool | Print query as first output line |
 | `--color` | ColorMode | Color mode: auto, none |
 | `--height` | string | Terminal height spec |
+| `--mouse` | bool | Enable mouse reporting (off by default; OR'd with `Mouse` config) |
 
 ## Exit Codes
 

Changes

@@ -6,8 +6,9 @@ v0.6.1 - UNRELEASED
   * Mouse reporting is now disabled by default. Enabling it (as v0.6.0
     did unconditionally) prevents the terminal's own text selection,
     e.g. select-and-copy in iTerm2 is blocked. To bind mouse buttons
-    (`MouseLeft`/`MouseMiddle`/`MouseRight`) to actions, set
-    `"Mouse": true` in your config file (#823).
+    (`MouseLeft`/`MouseMiddle`/`MouseRight`) to actions, enable it with
+    the `--mouse` command line option or `"Mouse": true` in your config
+    file (#823).
 
 v0.6.0 - 24 Feb 2026
   [Breaking Changes]

README.md

@@ -437,6 +437,12 @@ Without `--height`, peco uses the full terminal screen (default behavior, unchan
 
 **Note:** In inline mode, peco sets the environment variable `TCELL_ALTSCREEN=disable` to prevent tcell from using the alternate screen buffer, and restores the original value on exit. If peco is killed abnormally (e.g. `SIGKILL`), you may need to unset this variable manually: `unset TCELL_ALTSCREEN`.
 
+### --mouse
+
+Enables terminal mouse reporting so you can bind mouse buttons (`MouseLeft`, `MouseMiddle`, `MouseRight`) to actions in your `Keymap`.
+
+Mouse reporting is disabled by default because it prevents the terminal's own text selection (for example, select-and-copy in iTerm2 is blocked while mouse reporting is on). This flag is equivalent to setting `"Mouse": true` in the config file; the two are OR'd together, so either one enables it.
+
 # Configuration File
 
 peco by default consults a few locations for the config files.
@@ -525,6 +531,9 @@ terminal's own text selection (for example, select-and-copy in iTerm2 is
 blocked while mouse reporting is on). Only turn this on if you actually bind
 mouse buttons to peco actions.
 
+This is equivalent to the `--mouse` command line option; the two are OR'd
+together, so either one enables mouse reporting.
+
 Default value for Mouse is false.
 
 ### OnCancel

contrib/man/peco.1

@@ -741,6 +741,18 @@ behavior, unchanged).
 alternate screen buffer, and restores the original value on exit.
 If peco is killed abnormally (e.g.\ \f[V]SIGKILL\f[R]), you may need to
 unset this variable manually: \f[V]unset TCELL_ALTSCREEN\f[R].
+.SS \[en]mouse
+.PP
+Enables terminal mouse reporting so you can bind mouse buttons
+(\f[V]MouseLeft\f[R], \f[V]MouseMiddle\f[R], \f[V]MouseRight\f[R]) to
+actions in your \f[V]Keymap\f[R].
+.PP
+Mouse reporting is disabled by default because it prevents the
+terminal\[cq]s own text selection (for example, select-and-copy in
+iTerm2 is blocked while mouse reporting is on).
+This flag is equivalent to setting \f[V]\[dq]Mouse\[dq]: true\f[R] in
+the config file; the two are OR\[cq]d together, so either one enables
+it.
 .SH Configuration File
 .PP
 peco by default consults a few locations for the config files.
@@ -850,6 +862,9 @@ terminal\[cq]s own text selection (for example, select-and-copy in
 iTerm2 is blocked while mouse reporting is on).
 Only turn this on if you actually bind mouse buttons to peco actions.
 .PP
+This is equivalent to the \f[V]--mouse\f[R] command line option; the two
+are OR\[cq]d together, so either one enables mouse reporting.
+.PP
 Default value for Mouse is false.
 .SS OnCancel
 .IP

options.go

@@ -33,6 +33,7 @@ type CLIOptions struct {
 	OptPrintQuery      bool             `long:"print-query" description:"print out the current query as first line of output"`
 	OptColor           config.ColorMode `long:"color" description:"color mode: 'auto' (default, parse ANSI codes) or 'none' (disable)" default:"auto"`
 	OptHeight          string           `long:"height" description:"display height in lines or percentage (e.g. '10', '50%')"`
+	OptMouse           bool             `long:"mouse" description:"enable mouse reporting. disabled by default because it\nblocks the terminal's own text selection (e.g. copy in iTerm2)"`
 }
 
 // parse parses command-line arguments and validates the resulting options.

peco.go

@@ -817,6 +817,11 @@ func (p *Peco) ApplyConfig(opts CLIOptions) error {
 		p.heightSpec = &spec
 	}
 
+	// Mouse: --mouse forces it on; otherwise the config value applies.
+	if opts.OptMouse {
+		p.config.Mouse = true
+	}
+
 	p.populateFilters()
 
 	if err := p.populateKeymap(); err != nil {

peco_test.go

@@ -469,6 +469,35 @@ func TestApplyConfig(t *testing.T) {
 		require.False(t, p.heightSpec.IsPercent, "p.heightSpec.IsPercent should be false for absolute CLI value")
 	})
 
+	t.Run("Mouse off by default", func(t *testing.T) {
+		p := newPeco()
+
+		var opts CLIOptions
+		require.NoError(t, p.ApplyConfig(opts), "p.ApplyConfig should succeed")
+
+		require.False(t, p.config.Mouse, "mouse should be off when neither --mouse nor config is set")
+	})
+
+	t.Run("--mouse enables mouse", func(t *testing.T) {
+		p := newPeco()
+
+		var opts CLIOptions
+		opts.OptMouse = true
+		require.NoError(t, p.ApplyConfig(opts), "p.ApplyConfig should succeed")
+
+		require.True(t, p.config.Mouse, "p.config.Mouse should be true when --mouse is set")
+	})
+
+	t.Run("config Mouse honored when --mouse absent", func(t *testing.T) {
+		p := newPeco()
+		p.config.Mouse = true
+
+		var opts CLIOptions
+		require.NoError(t, p.ApplyConfig(opts), "p.ApplyConfig should succeed")
+
+		require.True(t, p.config.Mouse, "config Mouse:true should be preserved when --mouse is absent")
+	})
+
 	t.Run("Config OnCancel used when CLI option absent", func(t *testing.T) {
 		p := newPeco()
 		p.config.OnCancel = config.OnCancelError