命令行参考
CLI Finder 命令行工具
从终端搜索 Registry、检查工具，并把 Skill、Agent 策略或 JSON Manifest 写入 stdout。
从仓库检出目录运行
CLI 使用 Node.js 18.17 或更高版本且没有运行时依赖。当前 packages/cli 是 private 包，尚未发布到 npm。
使用 npm exec
shell
git clone https://github.com/chaoshipit/clifinder-net.git
cd clifinder-net
npm exec --package ./packages/cli -- clifinder help直接使用 Node.js
shell
git clone https://github.com/chaoshipit/clifinder-net.git
cd clifinder-net
node packages/cli/bin/clifinder.mjs help不要使用公共 npm 安装命令
当前不要运行 npm install -g clifinder 或 npx clifinder。上面的 npm exec --package ./packages/cli 使用的是本地仓库目录，不会宣称或依赖一个已经发布的 npm 包。
搜索与检查
默认输出面向人阅读；在任意命令中加入 --json 可获得可解析 JSON。搜索没有结果时退出码为 3。
search
用自然语言任务搜索，并应用 Agent、环境、风险、输出、分类、证据或数量过滤。任务可以由多个位置参数组成。
shell
npm exec --package ./packages/cli -- clifinder search \
"review pull requests" \
--agent codex \
--environment headless \
--risk R0 \
--output json \
--limit 5inspect
按 Slug 读取单个工具，终端输出包含命令、发布者、Readiness、风险、证据、输出和推荐安装。
shell
npm exec --package ./packages/cli -- clifinder inspect github-cli
npm exec --package ./packages/cli -- clifinder inspect github-cli --json \
| jq '{slug, readiness: .readiness.score, risk: .operationalRisk.defaultLevel}'| 搜索选项 | 允许值 | 说明 |
|---|---|---|
| --agent | claude | codex | gemini | copilot | 也接受 claude-code、gemini-cli 和 copilot-cli 等规范名称。 |
| --environment | local | ci | container | headless | remote | 传递到 Registry API 的环境过滤器。 |
| --risk | R0 | R1 | R2 | R3 | CLI 会把小写输入转换为大写，再由 API 验证。 |
| --output | format | 例如 json、yaml 或 csv。 |
| --category | category slug | 例如 code-collaboration 或 data-text。 |
| --evidence | confidence | 例如 verified 或 docs-verified。 |
| --limit | 1–100 | CLI 在请求前验证整数范围。 |
| --json | flag | 输出 Registry data 对象，而不是 code/message/data HTTP 包装。 |
生成 Skill、策略与 Manifest
skill 和 policy 必须指定 --agent，mode 默认 read-only。生成内容写入 stdout，因此可以使用 shell 重定向保存。
skill
shell
npm exec --package ./packages/cli -- clifinder skill github-cli \
--agent codex --mode read-only > SKILL.mdpolicy
shell
npm exec --package ./packages/cli -- clifinder policy github-cli \
--agent claude --mode standard > claude-settings.jsonjson
shell
npm exec --package ./packages/cli -- clifinder json github-cli \
> github-cli.clifinder.json| 命令 | 用法 | 输出 |
|---|---|---|
| skill | skill <slug> --agent <agent> [--mode <mode>] | 默认把 SKILL.md 内容写到 stdout；--json 返回 Artifact data 对象。 |
| policy | policy <slug> --agent <agent> [--mode <mode>] | Claude、Codex 和 Gemini 生成各自策略；Copilot 生成 AGENTS.md。 |
| json | json <slug> | 默认解析并重新格式化单工具 JSON Manifest；--json 返回包含 content 的 Artifact data 对象。 |
| --mode | read-only | standard | advanced | 生成策略的权限强度；默认 read-only。 |
帮助、版本和 API 地址
help 可读取总览或单条命令用法。version、--version 和 -v 输出当前 CLI 版本。CLIFINDER_API_URL 可把客户端指向本地或其他部署。
shell
node packages/cli/bin/clifinder.mjs help
node packages/cli/bin/clifinder.mjs help search
node packages/cli/bin/clifinder.mjs version
node packages/cli/bin/clifinder.mjs --version --jsonshell
CLIFINDER_API_URL=http://localhost:3000 \
node packages/cli/bin/clifinder.mjs search "parse yaml" --jsonCLIFINDER_API_URL
默认值为 https://clifinder.net。值必须是有效的 http 或 https URL；CLI 会删除末尾斜杠，并在其后追加 /api/registry/...。网络请求 15 秒超时并跟随重定向。
稳定退出码
脚本应根据退出码分支，而不是解析人类可读错误文本。错误写入 stderr；成功内容写入 stdout。
| 退出码 | 含义 | 处理建议 |
|---|---|---|
| 0 | 成功 | 命令已完成，可消费 stdout。 |
| 2 | 用法错误 | 命令、选项或位置参数缺失/未知，或者 Agent、mode、Limit、API URL 无效。 |
| 3 | 未找到 | 搜索没有结果，或 Registry API 对工具返回 404。 |
| 4 | 网络失败 | 连接失败、DNS 错误或 15 秒超时；可以按策略重试。 |
| 5 | API 或响应错误 | 过滤值被 API 拒绝、其他非 404 API 错误、非 JSON 响应、缺少 data 或 Artifact 格式无效。 |
shell
if node packages/cli/bin/clifinder.mjs inspect github-cli --json > tool.json; then
jq '.readiness.score' tool.json
else
status=$?
echo "clifinder failed with exit code $status" >&2
exit "$status"
fi