跳到主要内容

CLI

Gety 自带命令行工具,可以在终端中搜索文件、打开搜索界面、获取文档内容和管理连接器。

设置​

  1. 打开 Gety → 设置 → AI 集成,在 更多方式 下点击 CLI 命令

Gety AI 集成 页面,显示 更多方式 下的 CLI 命令 Gety → 设置 → AI 集成:点击 更多方式 下的 CLI 命令

  1. Gety 会将 gety 命令安装到你的 PATH 中,并显示 CLI 文档。你可以浏览各个命令,或点击 复制全部 复制完整文档。

Gety CLI 文档对话框,显示命令和选项 你的 CLI 文档 — 点击 复制全部 复制全部内容

重启终端

开启 CLI 命令 后,你必须关闭并重新打开终端(或新建一个终端会话),PATH 更改才会生效。在此之前 gety 命令将无法识别。

搜索​

gety search "合同续签条款"

搜索结果显示文档标题、匹配片段和文件路径。

如果你想在 Gety 应用里打开同一次搜索,而不是在终端中打印结果:

gety search "合同续签条款" --ui

选项​

gety search "预算报告" --limit 5 # 限制结果数
gety search "会议纪要" --ext pdf --ext docx # 按文件类型过滤
gety search "Q1 营收" --json # JSON 输出
gety search "设计规范" --no-semantic-search # 仅关键词搜索
gety search "contract" --match-scope content # 仅搜索内容
gety search "发票" --folder ~/Documents/Finance # 仅搜索某个文件夹
gety search "方案" --ui --folder ~/Projects # 在 Gety 中打开限定范围的结果
参数说明
-n, --limit <n>最大结果数(默认:10)
--offset <n>分页偏移(默认:0)
-c, --connector <name>按连接器名称过滤。可重复,也可用逗号分隔多个值。
-e, --ext <ext>按文件扩展名过滤。可重复,也可用逗号分隔多个值。例如可以写 pdf、.pdf、docx,或其它已索引文件扩展名。
--match-scope <scope>title、content 或 semantic。可重复,也可用逗号分隔多个值。
--sort-by <field>default 或 update_time
--sort-order <order>ascending 或 descending
--update-time-from <iso8601>按修改时间过滤,例如 2026-07-01T00:00:00Z
--update-time-to <iso8601>按修改时间过滤,例如 2026-07-31T23:59:59Z
--no-semantic-search禁用语义搜索
--folder <path>仅搜索某个文件夹。该文件夹必须已经位于某个已索引的连接器下。可重复。
--ui打开 Gety 搜索界面,而不是在终端中打印结果。可以只和查询词一起使用,也可以配合 --folder 打开限定文件夹范围的搜索。
--json以 JSON 格式输出。这是全局选项,适用于所有 CLI 命令。
备注

--ui 用于交互式打开 Gety。UI 模式只会应用查询词和 --folder。如果它和 --connector、--limit、--ext、--match-scope 等过滤参数一起使用,Gety 会忽略这些过滤参数并打印警告。

获取文档​

gety doc <connector_id> <doc_id>
gety doc <connector_id> <doc_id> --page-start 1 --page-end 3

获取文档的完整内容与详情。connector_id 和 doc_id 在搜索结果中返回。

参数说明
--page-start <n>要返回的第一页,页码从 1 开始
--page-end <n>要返回的最后一页,页码从 1 开始

你可以只提供 --page-start 或只提供 --page-end 来表示开放区间。页码过滤只适用于支持按页读取的文档类型。

处理大文件技巧

对于大型文档(长篇 PDF、大表格或日志文件),一次性输出所有内容可能会刷屏并打满 AI Agent 的上下文窗口。

推荐做法:

  • 存为临时文件并通过 grep 检索:
    gety doc folder_1 doc_123 > /tmp/doc.txt
    grep -i -C 3 "合同违约" /tmp/doc.txt
  • 分页获取:
    gety doc folder_1 doc_123 --page-start 1 --page-end 3

管理连接器​

Gety CLI 支持管理本地文件夹连接器以及自定义连接器(Custom Connectors)。

子命令​

# 列出连接器
gety connector list # 列出文件夹(传统格式)
gety connector list --kind custom # 列出自定义连接器
gety connector list --kind all # 列出所有连接器(统一格式)

# 查看连接器详情、配置与权限
gety connector show <connector_id>

# 文件夹管理
gety connector add ~/Documents # 添加文件夹到索引
gety connector add ~/Projects --name work # 添加并自定义名称
gety connector add C:\ # Windows 上添加 NTFS 卷根目录
gety connector remove <connector_id> # 移除连接器

# 自定义连接器管理
gety connector install ./my-connector --dry-run # 预览,不实际安装
gety connector install ./my-connector # 从本地文件夹安装
gety connector install --github <owner>/<repo> # 从 GitHub Release 安装
gety connector install --npm <package> # 从 npm 包安装
gety connector configure <connector_id> # 重新配置参数或同步计划
gety connector poll <connector_id> # 立即同步
gety connector rebuild <connector_id> # 删除文档并从头重建索引
gety connector restart <connector_id> # 重启连接器工作进程
gety connector enable <connector_id> # 启用连接器
gety connector disable <connector_id> # 禁用连接器
gety connector outdated # 列出有新版本的 npm 连接器
gety connector update <connector_id> # 更新 npm 连接器

connector add 需要一个目录路径。在 Windows 上,如果添加的是 C:\ 这样的卷根目录,并且该卷可用,Gety 会创建 NTFS 连接器;其它目录会创建文件夹连接器。使用 --name 可以设置 Gety 中显示的名称。

对自定义连接器,connector show 还会列出它拥有的权限,以及代码来源:本地文件夹、GitHub 仓库或 npm 包。

connector remove 不会要求确认,它会删除连接器及其已索引数据。从本地文件夹安装的自定义连接器,文件夹会保留;从 GitHub 或 npm 安装的,Gety 会删除自己保存的代码副本。

安装自定义连接器​

只能指定一个来源:本地文件夹、--github 或 --npm。

gety connector install ./my-connector
gety connector install --github acme/gety-my-connector
gety connector install --github https://github.com/acme/gety-my-connector/releases/tag/v1.2.0
gety connector install --npm @acme/gety-my-connector
gety connector install --npm @acme/gety-my-connector@1.2.0
  • 本地文件夹:Gety 直接从这个文件夹运行连接器,所以请保留它。Gety 只在安装时读取 manifest.json;要让 manifest 的修改生效,先运行 connector remove,再重新安装。
  • --github 支持 owner/repo、仓库链接或 Release 链接。默认安装 GitHub 标记为 Latest 的 Release。
  • --npm 支持 name、@scope/name、name@版本号,或 https://www.npmjs.com/package/<name> 链接(可以带 /v/<版本号> 结尾)。默认安装 latest dist-tag 指向的版本。
  • --version 指定从 GitHub(Release tag,例如 v1.2.0,或版本号,例如 1.2.0)或 npm(确切的版本号)安装的版本。输入中已经包含版本时,不要再使用它。

--dry-run 只显示安装预览和请求的权限,不会安装任何东西。对 GitHub 和 npm,预览只下载 Release 的 manifest.json 或包的 registry 元数据。从 GitHub 或 npm 安装最长可能需要 6 分钟。

每次安装都需要你同意连接器的权限。CLI 会把权限摘要写到 stderr,然后:

  • 传入 --yes 时,直接安装,不再询问。
  • 在终端中,用 [y/N] 请你确认。除 y 或 yes 之外的任何回答都会以 consent_declined 结束,不做任何修改。
  • 其他情况下,以 consent_required 结束,不做任何修改。请先用 --dry-run 审查权限,再加上 --yes 重新运行。

当 --config - 或 --secret 从 stdin 读取时,stdin 无法再回答确认提示,因此需要传入 --yes;否则命令会以 stdin_conflict 结束。如果连接器的权限在预览和安装之间发生变化,安装会以 permissions_changed 结束;重新运行以审查新的权限。

同步或重建连接器​

connector poll 会同步一个自定义连接器,或更新文件夹的索引。connector rebuild 会删除该连接器的全部文档,然后从头重新索引;对于大文件夹,这可能需要很长时间。两个命令都只报告请求已被接受,不等待完成,并且都会拒绝已禁用的连接器。connector rebuild 不会要求确认。

更新从 npm 安装的连接器​

gety connector outdated
gety connector update <connector_id> --dry-run
gety connector update <connector_id>
gety connector update <connector_id> --version 1.0.0 --yes

connector outdated 会检查所有从 npm 安装的连接器,每个有更新的连接器输出一行:<connector_id> <name> <installed> → <update>;没有更新时输出 All connectors are up to date。更新是比已安装版本新、不是预发布、没有弃用、并且能在当前 Gety 上运行的版本中最高的一个。

connector update 会切换到这个更新;传入 --version 时切换到指定的确切版本,包括旧版本、预发布版本和已弃用的版本。没有更新时,它会输出 Already up to date (<version>)。切换前,它会把预览写到 stderr:是否删除该连接器的文档并从头同步,哪些配置项会被删除、重置或仍需填写,以及新版本新增了哪些权限。确认方式与 connector install 相同。

配置会保留到新版本。--config、--set、--secret 和 --secret-file 可以修改这些配置,并填写新版本需要的配置项。更新成功时输出 Updated <connector_id> to <version>,连接器会以新版本重新启动。从 GitHub 或本地文件夹安装的连接器会以 capability_not_supported 拒绝 connector update。

安装、更新与配置选项​

参数适用命令说明
--github <input>install从 GitHub Release 安装
--npm <input>install从 npm 包安装
--version <version>install、update要安装或切换到的版本
--yesinstall、update不再询问,直接授予权限或切换
--dry-runinstall、update显示预览和权限,无任何副作用
--config <file>install、update、configureJSON 配置文件路径,或输入 - 从标准输入读取
--set <key=json>install、update、configure设置配置字段(如 --set workspace='"acme"'),可重复使用;不能用于密码字段
--secret <key>install、update、configure在终端交互式输入密码字段的值(通过 stderr 提示)
--secret-file <key=path>install、update、configure从文件读取密码字段的值(最多去除一个末尾换行符,上限 1 MiB)
--schedule <strategy>configure同步计划:manual、interval 或 daily
--every <duration>configure间隔时间,用于 --schedule interval(如 60s、5m、1h,最低 60s)
--at <HH:MM>configure每天固定同步时间,用于 --schedule daily(24 小时制)

connector configure 不会修改你没有指定的配置项,包括密钥。

连接器错误​

连接器命令失败时,错误信息会在方括号中给出以下错误类型之一,例如 [not_found]。使用 --json 时,错误类型在 error.kind 中。

类型含义
not_found没有这个 ID 的连接器。用 gety connector list --kind all 查看 ID。
already_installed已经安装了 manifest ID 相同的连接器。
version_incompatible这个版本需要更新的 Gety。请升级 Gety,或安装旧版本。
invalid_github_input、invalid_npm_input无法识别地址或版本。
release_not_foundGitHub 仓库不是公开的、没有 Release,或 Release 中没有 manifest.json。
package_not_foundnpm 包或版本不存在,或不是公开的。
source_unavailable无法连接 GitHub 或 npm registry。
invalid_packageRelease 或 npm 包不符合连接器的发布约定。
consent_required、consent_declined、stdin_conflict没有授予权限。参阅安装自定义连接器。
secret_input_required没有终端时,--secret 无法提示输入。请改用 --secret-file。
permissions_changed预览之后权限发生了变化。请重新运行命令。
validation_failed配置无效或缺少必填值,或者预览已过期。
capability_not_supported该连接器不支持这个命令。
not_running连接器已禁用或没有在运行。请启用或重启它,然后重试。退出码为 69 时,表示 Gety 本身没有运行。
applied_but_restart_failed更新或配置修改已经生效,但连接器没能重新启动。先用 gety connector show <connector_id> 查看,再运行 gety connector restart <connector_id>。

输出 JSON​

如果需要结构化输出,可以给任意命令添加 --json:

gety --json search "客户提案"
gety connector list --json
gety doc <connector_id> <doc_id> --json

成功时,JSON 会输出到 stdout。结构化错误详情会输出到 stderr。

配合 AI agent 使用​

CLI 适用于能运行 shell 命令的 AI agent(如 Claude Code、Codex)。Agent 可以在执行任务时调用 gety search 查找相关文件。

给 agent 的示例提示:

"使用 gety search 搜索我本地文件中与客户提案相关的文档,然后总结要点。"

如果需要 agent 更方便地解析输出,使用 JSON 格式:

gety search "客户提案" --json
交给 AI agent

和 API 一样,你可以复制完整的 CLI 文档粘贴到 agent 的对话中。Agent 会知道如何替你调用 gety 命令。

退出码​

退出码含义
0成功
1一般错误
2参数无效
69Gety 未运行
75请求超时
76无法连接到 Gety IPC
77已达到每月额度,详见 FAQ:免费版和 Pro

如果返回退出码 69,请确认 Gety 桌面应用正在运行。