peco CLI 完全指南：入口实现、全部命令行参数、退出码与输入输出协议

• 开发工具
• CLI

【免费下载链接】peco

Simplistic interactive filtering tool

项目地址：https://gitcode.com/gh_mirrors/pe/peco

点击查看免费下载

peco是一款用 Go 编写的简化版交互式过滤工具（Simplistic interactive filtering tool），它从 stdin 或文件读取行内容，让你一边输入查询一边实时过滤，最终把选中的行输出到 stdout 供下游命令继续消费。本文以仓库内的 CLI 参考文档（.claude/docs/cli.md）为骨架，结合cmd/peco/peco.go、options.go、peco.go 与 README.md 的源码实现，完整梳理 peco 的命令行入口、全部参数语义、退出码约定以及输入输出协议，帮助你掌握 peco 在脚本、管道与日常终端工作流中的正确用法。

入口点与启动流程

peco 的程序入口位于 cmd/peco/peco.go。main()先注册一个recover()兜底，随后调用_main()；_main()的核心逻辑只有三步：

1. 创建context，用于在整个生命周期内协调取消操作；
2. 调用peco.New()构造全局的Peco实例（见 peco.go，内部初始化内存行缓冲、ID 生成器、查询执行状态、tcell 屏幕与选择集合）；
3. 调用cli.Run(ctx)启动整套 TUI 管线，并根据返回错误类型决定进程退出码。

Run()（peco.go）内部依次执行：

• Setup()：初始化默认配置 → 解析命令行参数 → 读取配置文件 → 将参数与配置合并应用到运行时（ApplyConfig）→ 创建消息总线；
• parseCommandLine()（peco.go）：使用go-flags解析argv，同时处理--help与--version的立即返回逻辑；若未指定--rcfile，则调用config.LocateRcfile自动查找配置文件；
• SetupSource()（peco.go）：确定输入来源并启动读取协程，阻塞到收到第一行数据；
• 启动屏幕、输入循环、视图循环与过滤循环四个 goroutine，随后进入<-ctx.Done()等待用户操作结束。

从源码结构看，命令行参数解析是整个启动流程中最早的一环，其解析结果直接影响后续配置加载与运行时状态组装，因此理解每个参数的语义是使用 peco 的第一步。

命令行参数总览

CLIOptions结构体（options.go）以go-flags的 struct tag 定义了全部命令行参数。下表为完整清单（与 CLI 文档逐项对应）：

Flag	类型	说明
--help（-h）	bool	显示帮助信息并退出
--version	bool	显示版本号并退出
--query	string	启动时的初始查询字符串
--rcfile	string	配置文件路径
--buffer-size（-b）	int	搜索缓冲保留的最大行数（0 表示不限）
--null	bool	使用 NUL（\0）作为行分隔/结果标记
--initial-index	int	初始光标位置（0 起）
--initial-filter	string	初始过滤器名称
--filter	[]string	注册的过滤器列表（按轮转顺序，可重复），覆盖配置项Filters；未知名称报错
--negation-prefix	*string	排除行的查询词前缀（默认-），传空串关闭负向匹配，覆盖配置项NegationPrefix
--prompt	string	查询行提示符
--layout	string	布局：top-down、bottom-up、top-down-query-bottom
--select-1	bool	输入仅 1 行时自动选中并立即退出
--exit-0	bool	输入为空时立即以状态 1 退出（部分文档中写作--exit-zero，源码 tag 为long:"exit-0"，指同一开关）
--select-all	bool	全选所有行并立即退出
--on-cancel	string	取消行为：success/error
--selection-prefix	string	选中行的前缀标记（默认用颜色区分）
--exec	string	将选中内容通过管道交给指定命令执行
--print-query	bool	输出结果时把查询字符串作为第一行打印
--color	ColorMode	颜色模式：auto、none
--height	string	终端高度规格（如10、50%）

此外，源码中还定义了文档表格未列出、但实际可用的-f, --follow（跟随流式输入自动滚动，类似tail -f，见 options.go），阅读时可一并参考。

参数解析完成后会执行Validate()（options.go）：当--layout非空时，必须命中config.IsValidLayoutType中定义的三种布局之一，否则返回unknown layout错误。

参数详解与源码级语义

基本信息类：--help、--version

--help会通过反射遍历CLIOptions的 struct tag 自动生成对齐的帮助文本（options.go），并返回一个"可忽略错误"让进程以 0 退出；--version则打印peco version v0.6.0 (built with go1.x)格式的版本信息（版本号定义于 peco.go）。

查询与过滤类

• --query <string>：设置启动时的初始查询。设置后游标会自动定位到查询串末尾（utf8.RuneCountInString，见 peco.go），并在 peco 就绪后立即执行一次过滤。适合在脚本中提前猜出最可能的查询词，如cd $(ghq list --full-path | peco --query peco)。
• -b, --buffer-size <num>：限制 peco 在任何时刻持有的行数上限，0（默认）表示不限制。对可能无限增长的流式输入尤其重要，可防止内存被耗尽。
• --null：启用 NUL 分隔模式。每行输入中\0之前的部分用于显示与匹配，\0之后的部分作为退出时输出的"结果"。该开关在源码中对应enableSep字段，并会传递给Source与外部过滤器（peco.go）。
• --initial-index <int>：0 起始的初始光标行号。例如想从第二行开始选中，传入1（peco.go 中>= 0才生效）。
• --initial-filter <name>：指定启动时使用的过滤器，名字须为IgnoreCase、CaseSensitive、SmartCase、IRegexp、Regexp、Fuzzy之一，或自定义过滤器名。若名字无效，populateInitialFilter会报failed to set filter错误。
• --filter <name>：可重复指定，按给定顺序注册过滤器，peco.RotateFilter（默认绑定C-r）只在这几个过滤器间轮转。默认情况下注册全部内置过滤器及所有自定义过滤器；一旦指定--filter，则以命令行为准，覆盖配置文件Filters段。未知名字会触发错误并列出可接受的过滤器名（peco.go）。注意--initial-filter指定的名字必须属于已注册集合。
• --negation-prefix <string>：定义"排除词"前缀，默认-。空值关闭负向匹配，所有词按原样匹配；换其他字符（如!）则保留负向匹配同时让连字符参与字面匹配。该值最终经filter.WithNegationPrefix注入每个过滤器（filter/option.go），负向词通过正则排除实现（isExcluded，见 filter/filter.go）。命令行写法建议带=：--negation-prefix=，否则以-开头的值会被当作新选项解析。

界面与布局类

• --prompt <string>：查询行提示符，默认QUERY>（config.DefaultPrompt，见 config/config.go）。命令行优先级高于配置文件的Prompt。
• --layout <type>：三种取值对应三种屏幕排布——top-down（默认，提示符在顶、列表居中、状态行在底）、bottom-up（列表逆序显示在顶、提示符在下）、top-down-query-bottom（列表在顶、查询提示符沉底）。对 percol 用户而言，--layout=bottom-up约等于--prompt-bottom --result-bottom-up。
• --height <num|percentage>：让 peco 以"内联"模式在终端底部渲染指定行数，而不是占满整个备用屏幕，从而保留上方滚动历史（类似 fzf 的--height）。绝对值--height 5表示 5 行结果区，提示符与状态栏自动追加（共 7 行）；百分比--height 50%表示占终端总高度（含提示符与状态栏）的比例。最小有效高度为 3 行（1 行结果 + 提示符 + 状态栏），超出终端高度会被截断——这些规则由 config/height.go 的Resolve实现，ChromLines = 2常量即提示符与状态栏占用的行数。内联模式还会设置环境变量TCELL_ALTSCREEN=disable阻止 tcell 使用备用屏幕缓冲，异常终止（如SIGKILL）后可能需要手动unset TCELL_ALTSCREEN。
• --color auto|none：控制输入中 ANSI SGR 转义序列的解析与渲染。auto（默认）保留git log --color、rg --color=always等管道输入的颜色；none则剥离转义序列。匹配过滤始终针对剥离后的纯文本进行，输出时保留原始 ANSI 码。该开关只影响"输入 ANSI 颜色"这一层，与配置Style控制的 UI 样式（选中高亮、匹配高亮等）相互独立。
• --selection-prefix <string>：用指定前缀代替变色来标记当前选中行（实验性），默认仍以颜色区分。等价于配置文件中的SelectionPrefix。

行为控制类

• --select-1：当且仅当输入恰好 1 行时，自动选中该行并立即退出，不进入交互界面。源码在selectOneAndExitIfPossible（peco.go）中通过 CAS 原子操作保证多 goroutine 并发下只触发一次。若输入有多行，则照常展示选择界面。
• --exit-0：输入为 0 行时立即以状态 1 退出。exitZeroIfPossible（peco.go）检查缓冲区为空后构造exitStatusError{status: 1}。
• --select-all：全选所有输入行并立即退出，不展示选择界面（selectAllAndExitIfPossible，peco.go）。当同时存在初始查询时会先执行查询再全选当前结果。
• --on-cancel success|error：定义用户按 Esc 取消时的退出语义。默认success（兼容历史行为，取消也返回 0）；error则返回非零状态。配置项OnCancel与其等价，命令行优先。OnCancelBehavior的合法值校验见 config/config.go。

上述三个"立即退出"开关（--select-1、--exit-0、--select-all）都由startEarlyExitHandlers（peco.go）以独立 goroutine 等待输入源SetupDone()后触发，适合批量脚本场景。

输出类

• --print-query：退出时把最终查询字符串作为输出的第一行打印。正常结束（回车确认）时即使没有匹配也会打印；按 Esc 取消时不会打印。实现见PrintResults（peco.go）。
• --exec <command>：不再"选出即退出"，而是把当前选中的行通过 stdin 管道交给外部命令（经/bin/sh -c或cmd /c执行）。命令执行完毕后控制权返回 peco，可继续浏览搜索缓冲并重复执行；此时要真正退出 peco 需按 Esc（Cancel）。peco 自身最终的退出状态码继承自该外部命令的退出状态——这就是文档中"Custom — from--execcommand exit status"的来源。

退出码语义

peco 的退出码由 cmd/peco/peco.go 中的错误分类决定：

退出码	场景
0	成功（有行被选中并输出）
0	取消（默认行为，--on-cancel success）
1	取消且指定了--on-cancel error
自定义	--exec指定命令的退出状态码

底层机制：Run()返回的p.Err()会被包装为特定错误类型——collectResultsError触发结果打印并以 0 退出；ignorableError（如--help、--version）直接返回 0；exitStatusError（如--exit-0的空输入、--exec的子命令状态）携带ExitStatus()返回值；其余未知错误打印到 stderr 并以 1 退出。

输入处理：stdin、文件与流式输入

SetupSource的输入选择逻辑（peco.go）遵循三条规则：

1. 位置参数指向文件：命令行剩余参数（p.args[1]起）存在时，直接os.Open该文件作为输入；
2. 默认读 stdin：无位置参数且 stdin 不是 TTY 时，从 stdin 读取，并把该来源标记为isInfinite = true——这意味着后续查询无法使用批量模式，只能采用"发送即查 + 超时回调"的流式策略（sendQuery与waitAndCall，见 peco.go）；
3. 既无文件也无管道则报错：提示you must supply something to work with via filename or stdin。

典型用法：

# stdin 管道 ps aux | peco # 直接读文件 peco /var/log/nginx/access.log # 无限流 + 缓冲上限 journalctl -f | peco --buffer-size 1000

流式输入（isInfinite）还会影响--select-1的判定时机：由于无法等待过滤管线结束，源码采用 2 秒超时 + 100ms 轮询的waitAndCall机制做"尽力而为"的单行检查（peco.go）。

输出处理：选中行、查询首行与命令管道

退出时PrintResults（peco.go）按以下顺序产出：

1. 若当前没有任何选中行，则把光标所在行自动加入选择集，保证总有一条结果；
2. 若启用--print-query，先把查询字符串写入缓冲并追加换行；
3. 遍历选择集（按原始顺序Ascend），每行调用line.Output()输出到 stdout，逐行换行分隔。

三种输出模式的对比：

# 模式一：选中行逐行输出到 stdout ps aux | peco # 模式二：查询串作为第一行输出 ps aux | peco --print-query --query root # 输出示例： # root # root 12345 ... # 模式三：选中内容交给下游命令 ls *.go | peco --exec 'wc -l'

在--null模式下，输出的是每行\0之后的结果段，适合"显示 A 输出 B"的映射场景。

参数优先级：命令行 > 配置文件 > 内置默认值

从ApplyConfig（peco.go）的赋值顺序可以清晰归纳出 peco 的优先级约定：命令行选项优先于配置文件，配置文件优先于内置默认值。典型示例：

• --negation-prefix：先取filter.DefaultNegationPrefix（-），再被配置NegationPrefix覆盖，最后被命令行覆盖；
• --height：命令行OptHeight非空则用之，否则取配置Height；
• --filter/--initial-filter：OptFilters为空才回落到p.config.Filters，OptInitialFilter为空才回落p.config.InitialFilter；
• --follow：opts.OptFollow || p.config.Follow合并生效；
• --prompt、--on-cancel、--selection-prefix同理。

配置文件支持 JSON 与 YAML（按扩展名区分，见 config/config.go），未指定--rcfile时按顺序查找$XDG_CONFIG_HOME/peco/config.{json,yaml,yml}、~/.config/peco/...、$XDG_CONFIG_DIRS各目录及~/.peco/...（config/config.go）。

实战速查

# 最基础：管道过滤，回车选中，Esc 取消 ps aux | peco # 带初始查询与提示符，适合脚本预判 history | peco --query 'git' --prompt 'HIST>' # 多选并交给命令（配合 C-Space 多选） ls | peco --exec 'xargs cat' # 流式日志跟随 + 沉底布局 journalctl -f -n 1000 | peco --follow --layout top-down-query-bottom # 只注册两个过滤器轮转 peco --filter IgnoreCase --filter Fuzzy < input.txt # 禁用负向匹配（历史记录里满是连字符的场景） history | peco --negation-prefix= # 内联高度模式，保留终端滚动历史 ls | peco --height 40%

小结

peco 的 CLI 设计遵循"小而锐"的哲学：入口极简（New()+Run(ctx)），参数全部收敛在CLIOptions结构体中，退出码、输入来源与输出格式都有清晰而稳定的契约。理解这些命令行语义——尤其是--filter/--negation-prefix/--height/--exec这类与配置项联动的参数，以及"命令行 > 配置 > 默认值"的优先级规则——能让你在 shell 脚本、日志检索与文件导航场景中把 peco 用出最大的生产力。

赞分享

• 开发工具
• CLI

【免费下载链接】peco

Simplistic interactive filtering tool

项目地址：https://gitcode.com/gh_mirrors/pe/peco

点击查看免费下载

相关推荐

• Repomix CLI 命令行选项完全参考：从输入输出到安全、Token 计数与 Agent Skills

  Repomix CLI 命令行选项完全参考：从输入输出到安全、Token 计数与 Agent Skills Repomix 是一款将整个代码仓库打包为单个 AI

  开发工具MCP 服务AI 应用

• Stylelint 命令行接口（CLI）完全指南：参数详解、实战用法与退出码

  Stylelint 命令行接口（CLI）完全指南：参数详解、实战用法与退出码 Stylelint 是一款强大的 CSS 检查器（linter），帮助开发者避免样

  代码质量静态分析前端

• UniGetUI 命令行接口（CLI）完全指南：动词命令语法、自动化 IPC 传输与退出码详解

  UniGetUI 命令行接口（CLI）完全指南：动词命令语法、自动化 IPC 传输与退出码详解 导读 UniGetUI 在 2026 年发布的 CLI 重构中，

  桌面应用开发工具跨平台

上一篇：如何通过Zotero-GPT实现文献管理的智能革命：从手动整理到AI驱动的知识发现

下一篇：如何在ComfyUI中快速实现AI换脸：ReActor Node完整入门指南