CLI 使用#

better-edit-tools 除了作为 MCP server 运行外，还提供 8 个核心编辑工具的 CLI 子命令，适合 shell 脚本、Pi Agent 或偏好命令行调用的场景。

基本用法#

better-edit-tools <command> [options]

不带子命令时启动 MCP server（stdio）。

子命令#

文件操作#

read：读取文件行范围。
replace：替换指定行范围。
insert：在指定行后插入内容。
delete：删除指定行范围。
write：写入或覆盖文件。

内容识别#

balance：检查括号、引号、标签成对情况。
func-range：检测某行所在的函数或 {} 块范围。
tag-range：检测某行所在的 XML/HTML/Vue 标签范围。

常用示例#

# 读取 1-10 行
better-edit-tools read --file main.go --start 1 --end 10 --output json

# 替换指定范围
better-edit-tools replace --file main.go --start 5 --end 10 --content "..."

# 在第 4 行后插入
better-edit-tools insert --file main.go --after-line 4 --content "..."

# 删除指定范围
better-edit-tools delete --file main.go --start 5 --end 10

# 写入文件
better-edit-tools write --file main.go --content "package main\n"

# 结构检查 / 范围检测
better-edit-tools balance --file main.go
better-edit-tools func-range --file main.go --line 12
better-edit-tools tag-range --file index.html --line 8

管道与 stdin 支持#

为了避免 shell 引号转义问题，部分命令支持 --content-file 和 --old-file，并把路径设为 - 表示从 stdin 读取。

替换内容来自 stdin#

cat new_content.txt | better-edit-tools replace \
  --file main.go --start 5 --end 10 --content-file -

旧内容来自 stdin#

cat old_snippet.txt | better-edit-tools replace \
  --file main.go --start 5 --end 10 --old-file - --content "..."

写入文件时内容来自 stdin#

cat main.go | better-edit-tools write --file main.go --content-file -

通过 here-document#

better-edit-tools write --file main.go --content-file - <<'EOF'
package main

func main() {}
EOF

通用选项#

--output json：输出与 Go API 对应的结构化 JSON。
--preview：只返回 diff，不写入文件。
--brief：返回精简结果。
--lang <zh|en>：设置工具描述语言（仅影响 MCP server 模式）。
--no-prefix：隐藏工具名的 be- 前缀（仅影响 MCP server 模式）

注意事项#

基于 session 的特性（viewed_code_id 校验、快照/事务工具）仅在 MCP server 模式下可用，因为它们依赖进程内状态。
CLI 模式不引入 cobra / urfave/cli 等外部依赖，继续手写 flag parser，因此参数风格与 MCP schema 尽量保持一致。

📝 发起 issue