connector-cli

connector-cli 是观远连接器的命令行工具，用于查询连接器配置、分析 API、验证请求和排查同步任务，也可以配合 Codex 使用。

安装

需要 Node.js 18 或更高版本。

从 npm 公网仓库全局安装：

npm install --global @guandata/connector-cli

验证安装：

connector-cli version
connector-cli help

升级到最新版本：

npm install --global @guandata/connector-cli@latest

如需让 Codex 使用配套 skill：

connector-cli install-skill

install-skill 会先检查 package.json 中的运行时依赖；缺失时自动安装生产依赖，确认可加载后再安装 skill。

如何使用

安装 skill 后，可以直接向 Codex 描述目标，例如：

• “帮我看一下这张表对应哪个连接器 API”
• “分析这个 API 的前置依赖和分页参数”
• “校验这个 API JSON 是否能安全保存”
• “查一下昨天这个任务为什么失败”
• “为这个平台生成连接器接入文档”
• “按新版插件开发规范实现或检查这个平台插件”

Codex 会根据目标调用 connector-cli，并在执行真实请求或修改数据前向你确认。

也可以在终端中直接使用以下命令。

先登录连接器服务：

connector-cli login \
  --customer-code "<customerCode>" \
  --username "<username>" \
  --password "<password>"

Agent 服务中的无状态身份

Agent 服务不需要执行 connector-cli login。服务通过当前请求为 CLI 进程注入：

CONNECTOR_TOKEN
CONNECTOR_BASE_URL
CONNECTOR_CUSTOMER_CODE
CONNECTOR_USER_ID

存在 CONNECTOR_TOKEN 时，CLI 会构造只在当前进程有效的 agent profile。数据账户、数据库等 工作区选择仍保存在当前目录的 .connector-cli/config.json，但 Token 不会写入文件，也不会读取或 修改用户主目录下的全局配置。因此，只要 Agent 将命令工作目录设置为 Session Workspace，每个会话 就会拥有独立的 CLI 状态和临时文件。

说明：

• 不传 --agent 时，默认补 --agent codex
• 传了参数时，以你显式传入的参数为准

查看当前账号可用的平台和数据账户：

connector-cli whoami
connector-cli plat list
connector-cli plat availability
connector-cli plat market
# 如需查看完整后端响应：connector-cli plat market --raw
connector-cli datasource list --plat-code "<platCode>"
connector-cli datasource use "<datasourceNameOrId>"
connector-cli table ddl "<tableName>" --database-id "<databaseId>"

查询平台下的 API，或根据表名反查 API：

connector-cli api list --plat-code "<platCode>"
connector-cli api by-table --plat-code "<platCode>" "<tableName>"
connector-cli api info "<apiId>"

预览或更新接口同步模式与描述：

connector-cli api metadata "<apiId>"
connector-cli api metadata --plat-code "<platCode>" --plat-type "<platType>" --sync-mode-only

api metadata 会综合插件规则、官方文档、定时任务切窗、接口分片、分页和主子表主键生成同步模式。增量模式按 apiConfig.timeUnit/timeInterval 描述请求窗口，并说明 Cron 与本次触发时间如何确定同步范围。默认只预览；显式传 --confirm 才保存，--sync-mode-only 只更新 syncMode。

执行真实请求前，建议先预览参数：

connector-cli api prepare "<apiId>" --datasource-id "<datasourceId>"
connector-cli api request "<apiId>" --datasource-id "<datasourceId>"

排查同步任务时，可以查看任务状态和日志：

connector-cli task status "<instanceId>"
connector-cli task instance log "<instanceId>"

常用命令：

| 命令 | 作用 | | --- | --- | | connector-cli whoami | 查看当前登录和数据上下文 | | connector-cli plat list | 查看当前账号已可访问的平台及发布阶段说明 | | connector-cli plat availability | 查看平台发布阶段、可用状态、原因和订阅额度 | | connector-cli plat market [--raw] | 查看市场平台、发布阶段、平台标签及自研/服务商资质；可选完整响应 | | connector-cli datasource list | 查看数据账户 | | connector-cli table ddl | 通过连接器数据库通道导出迁移契约 DDL | | connector-cli api list | 查看平台 API | | connector-cli api info | 查看 API 详细配置 | | connector-cli api metadata | 预览或更新接口同步模式与描述 | | connector-cli api lint | 校验本地 API JSON | | connector-cli api prepare | 预览请求参数 | | connector-cli api request | 验证一次真实请求 | | connector-cli task run | 运行完整同步任务 | | connector-cli task instance log | 查看任务日志 |

完整命令和参数请运行：

connector-cli help

涉及 API 保存、删除或完整任务运行时，需要显式传入 --confirm。执行前请先检查命令输出中的 API、数据账户和目标表。

如果要切本地环境：

connector-cli login --local --customer-code "<customerCode>"

首次保存或更新某个账号密码时，在用户自己的终端通过标准输入登录：

connector-cli login --customer-code "<customerCode>" --username "<username>" --password-stdin

登录成功后，密码保存在系统凭据库；token、账号索引和 credentialId 保存在当前目录 profile。只传 customerCode 时使用当前环境下最早保存的账号，同时传 username 时精确选择账号。兼容参数 --password 仍可使用，但不应出现在 Agent 命令、共享脚本或聊天内容中。

Codex 沙箱无权读取已保存密码时，CLI 返回 KEYCHAIN_ACCESS_REQUIRED。Agent 应申请系统凭据访问权限并重试同一条无密码登录命令；这不表示密码未保存。只有 CREDENTIAL_NOT_FOUND 才需要用户通过同时包含 --username 和 --password-stdin 的命令首次录入或更新密码。

说明

• 真正的业务能力主要由 connector-server 提供
• CLI 负责本地 profile、datasource 上下文、命令路由、结构化输出
• 配置读取优先级是当前目录 ./.connector-cli/config.json，然后是全局 ~/.connector-cli/config.json
• 新目录第一次使用时，如果没有当前目录配置，会复制全局最后一次上下文到当前目录
• login、datasource use、database use 会同时更新当前目录上下文和全局最后一次上下文
• 密码使用 macOS Keychain、Windows Credential Manager 或对应系统凭据库保存；token 保存在权限为 0600 的当前目录配置中，以支持不同目录并行使用不同客户和环境
• token 失效时会使用当前身份的已保存密码自动登录，最多尝试 3 次、间隔 1 秒；成功后只重放原请求一次
• skills/connector-cli/ 负责告诉 Codex 这套命令怎么用
• skill 现在按四层组织：context / interfaces / playbooks / plugins
• 默认先确认 datasource，涉及前置表时再确认 database
• 客户先给表名时，可优先用 api by-table
• 排查时间窗口或失败任务时，可优先用 task schedule / task instance / task stats / task trend
• GUANDATA 管理上下文可按需查询某 API 被哪些客户的启用定时任务引用；该结果不代表历史使用客户
• 定时任务支持查询、创建、修改、启停和删除；所有调度写操作默认只预览，显式 --confirm 后才提交
• 默认建议先跑 api prepare，人工确认参数无误后再跑 api request
• 前置分析可先用 api pre-deps 和 api lineage
• 前置 TABLE 模式复现用 table preview
• 普通表事实核验或前置 SQL 模式排查用 table sql
• 如果要看“这个 API 支不支持查询校验参数”，可用 api valid-param
• api prepare / api request 默认会先读取 api info，再用 data.requestParam 作为执行骨架去调用 /connectorApi/request
• 如果传 --api-json <api.json>，会使用本地 JSON 草案里的 requestParam / customParameters / tableInfos 作为本次执行骨架，可先测试未保存配置，不会写入线上 API
• 具体执行必须绑定 datasourceId；如果不显式传 --datasource-id，则默认取当前已选数据账户
• --custom-params 用于补 ${xxx} 这类占位符参数，--pre-request-values 用于补 preRequestConfig.columns[].value
• api create / api update 都会写服务端，必须先确认 API JSON，再显式传 --confirm
• api create 要求 JSON 不带 apiId
• api update 要求 JSON 带 apiId，也可以通过 --api-id <apiId> 指定
• api delete 会删除 API 配置及关联任务；不带 --confirm 只预览删除目标，确认 apiId、名称、平台和表名后才允许执行
• 问题知识默认保存在当前项目 .connector-cli/knowledge/，不会混入登录配置
• knowledge search 通过 connector-mcp 服务检索知识库，并复用当前连接器登录 token
• knowledge rebuild 会通过 connector-mcp 更新远端文档并重新索引；本地 Markdown 和历史副本始终保留