auto-cli

A collection of thin CLI wrappers built for AI agents: predictable flags, JSON output, and rate-limit-aware by default.

给 AI agent 用的命令行工具集。每个工具都是对现有 CLI（gh、docker、kubectl…）的一层薄封装，目标只有三个：

1. 省配额 —— 绕开容易撞墙的接口，能缓存的就缓存。
2. 好解析 —— 一律提供 --json，默认输出是对齐的表格，人和模型都能读。
3. 零学习成本 —— flag 命名跨工具统一，--help 一屏内讲完。

工具清单

工具	底座	作用	状态
gh-auto-repo	gh	搜 GitHub 仓库，走 GraphQL 不吃 REST search 的 30/min 配额	✅ 可用
gh-auto-code	gh	在指定仓库里搜代码，不吃 code_search 的 10/min 配额	✅ 可用
auto-search	无头 Chrome	命令行搜网页，无 API key 无配额	✅ 可用

后续工具按同一套约定加进来，见下方「新增工具」和 AGENTS.md。

安装

git clone https://github.com/Francis-Xavier-code/auto-cli.git
cd auto-cli

# gh 扩展类
(cd gh-auto-repo && gh extension install .)
(cd gh-auto-code && gh extension install .)

# 独立命令类
(cd auto-search && npm install && ln -s "$PWD/auto-search" /usr/local/bin/)

依赖：gh ≥ 2.0、jq、curl；auto-search 另需 Node ≥ 18 和 Chrome。脚本兼容 bash 3.2（macOS 自带）。

⚠️ 两个坑：

1. gh extension install <owner>/<repo> 要求仓库名以 gh- 开头，本仓库是聚合仓库所以不满足，只能 clone 后本地装。
2. 本地安装必须 先 cd 进工具目录再 gh extension install .，从上层传 ./gh-auto-repo 会被当成远程仓库名而失败。

装完是软链到本仓库，git pull 即生效。不想用 extension 机制的话直接软链到 PATH：

ln -s "$PWD/gh-auto-repo/gh-auto-repo" /usr/local/bin/

新增工具

一个工具 = 一个目录，目录名即命令名。约定如下：

<命令名>/
├── <命令名>        # 可执行文件，无扩展名，chmod +x
├── README.md       # 用法、配额说明、已知限制
└── test.sh         # 自检，退出码 0 = 通过

必须满足的契约（AGENTS.md 里是完整版）：

• -h/--help 打印用法并 exit 0；参数非法时报错到 stderr 并 exit 1
• --json 输出裸 JSON，除此之外不往 stdout 写任何东西
• 涉及限流的接口要选配额宽松的通道，并在 README 里写明实测数字
• 有缓存的话：--no-cache 绕过，<TOOL>_TTL 环境变量调时长，失败结果不入缓存
• 留一个 test.sh，覆盖「这段逻辑坏了会怎样」，不引入测试框架

新工具加完后，把上面的「工具清单」补一行。

许可

MIT