@share-crm/sharecrm-cli

v1.1.3

Published

ShareCRM CLI client skeleton

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Maintainers

gouwengouwensharecrm-npmsharecrm-npm

Keywords

Readme

sharecrm CLI Client

fs-cli-client 是 sharecrm 命令行客户端的源码目录，用于访问远程命令能力，支持 OAuth 设备码登录、远程命令执行、命令帮助查询和请求级调试输出。

  • Node.js: >=18.17
  • npm package: sharecrm
  • CLI 命令名: sharecrm

功能概览

  • OAuth 设备码登录
  • 本地登录状态查询与退出登录
  • 远程命令执行
  • 本地帮助和远程命令帮助
  • --debug 调试输出
  • 会话元数据与密钥分离存储

平台支持

当前代码按平台选择不同的本地 secret store 后端：

| 平台 | 默认配置目录 | secret store | | --- | --- | --- | | macOS | ~/.sharecrm-cli | Keychain 保存主密钥，本地文件保存加密后的 secret | | Linux | ~/.sharecrm-cli | 本地 keychain/ 目录保存主密钥和加密后的 secret | | Windows | %USERPROFILE%\\.sharecrm-cli | PowerShell + DPAPI + HKCU:\\Software\\sharecrm-cli\\keychain |

说明：

  • 所有平台都会在配置目录下保存 config.json、会话锁文件和命令缓存。
  • Windows 运行依赖 powershell.exe。
  • FS_CLI_CONFIG_DIR 可覆盖默认配置目录。

安装

本地开发安装

npm install
npm run build
npm link

npm命令安装

npm install -g [email protected]

安装完成后可直接执行：

sharecrm --help

不全局链接的运行方式

构建后直接运行：

node dist/index.js --help

或直接从源码调试启动：

npm run build:debug -- --help

配置

通过环境变量配置认证地址、业务接口地址和本地状态目录：

| 变量名 | 是否必需 | 默认值 | 说明 | | --- |-----------| --- | --- | | FS_CLI_AUTH_BASE_URL | 认证相关命令必需 | 构建产物中的运行时配置 | OAuth 设备码登录相关接口地址，必须为 https:// | | FS_CLI_API_BASE_URL | 否 | 构建产物中的运行时配置 | 远程命令接口地址，必须为 https://。登录成功后如服务端返回 apiUrl，优先使用登录态中的地址 | | FS_CLI_CONFIG_DIR | 否 | <homeDir>/.sharecrm-cli | 本地配置、会话与缓存目录 | | FS_CLI_DEFAULT_CLIENT_ID | 否 | 构建产物中的默认值 | OAuth 设备码登录使用的客户端 ID |

homeDir 的解析规则：

  • macOS / Linux: 优先使用 os.homedir()，为空时回退到 HOME
  • Windows: 优先使用 os.homedir()，为空时回退到 USERPROFILE，再回退到 HOMEDRIVE + HOMEPATH

快速开始

1. 设置环境变量

macOS / Linux:

export FS_CLI_AUTH_BASE_URL="https://your-auth.example.com"
export FS_CLI_API_BASE_URL="https://your-api.example.com/cli/"

Windows PowerShell:

$env:FS_CLI_AUTH_BASE_URL = "https://your-auth.example.com"
$env:FS_CLI_API_BASE_URL = "https://your-api.example.com/cli/"

2. 登录授权

sharecrm auth login

执行后 CLI 会输出授权地址、设备验证码，并在授权完成后输出登录结果 JSON。例如：

在浏览器中打开以下链接进行认证:
https://your-auth.example.com/device
设备验证码: ABCD-EFGH
等待用户授权中...
{
  "success": true,
  "userId": "user-1",
  "appId": "FSAID_xxx",
  "scope": [
    "crm"
  ]
}

3. 查看帮助

sharecrm --help
sharecrm help
sharecrm help crm
sharecrm crm QueryRecords --help

说明：

  • 无登录态时，sharecrm 和 sharecrm help 仍会输出本地帮助
  • 已登录时，sharecrm help <command...> 会继续请求远程命令清单

4. 执行远程命令

sharecrm knowledge search WebSearchAction -d '{"query":"北京有什么好玩的"}'

也可以把 JSON 放在命令最后一个参数：

sharecrm knowledge search WebSearchAction '{"query":"北京有什么好玩的"}'

如果未传 -d / --data 且最后一个参数也不是 JSON，CLI 会默认发送空对象 {}。

命令说明

本地命令

sharecrm auth login
sharecrm auth status
sharecrm auth logout
sharecrm help [command...]
sharecrm --help
  • auth login: 发起 OAuth 设备码登录
  • auth status: 输出当前登录状态 JSON
  • auth logout: 清理本地登录态
  • help [command...]: 显示本地帮助或远程命令帮助

auth status 输出

sharecrm auth status 输出 JSON，当前包含以下字段：

  • appId
  • expiresAt
  • grantedAt
  • identity
  • scope
  • tokenStatus
  • userName
  • userId
  • cliVersion

其中：

  • tokenStatus = normal 表示本地 access token 存在且未过期
  • tokenStatus = needs_refresh 表示 access token 缺失、过期，或本地仅剩会话元数据

远程命令

sharecrm <command> -d '{...}'
sharecrm <command> --data '{...}'
sharecrm <command> '{...}'
sharecrm <command>

参数规则：

  • -d 与 --data 等价
  • 如果最后一个参数看起来像 JSON（{...} 或 [...]），会被识别为请求参数
  • 如果都没有提供，则默认使用 {} 作为请求参数
  • CLI 会要求 -d/--data 对应的值必须是合法 JSON 对象

调试

全局 --debug 参数会把远程接口请求、响应和异常信息输出到 stderr：

sharecrm --debug knowledge search WebSearchAction -d '{"query":"test"}'

说明：

  • --debug 是全局参数，建议放在命令前面
  • 正常结果输出到 stdout
  • 调试信息输出到 stderr
  • 遇到 CliError 时会附带结构化异常信息

认证与本地状态

  • config.json 仅保存 CLI 元数据和会话元数据，不保存 accessToken / refreshToken
  • accessToken / refreshToken 通过平台对应的 secret store 保存
  • 旧版明文 session.json 会在读取时尝试迁移
  • 当远程接口返回登录失效时，CLI 会尝试使用 refreshToken 刷新登录态
  • 刷新成功后会自动重试一次原请求
  • 刷新失败或缺少刷新所需信息时，会提示重新登录

重新登录提示示例：

提示：登录状态已失效，请重新登录授权。
执行命令：sharecrm auth login

常见问题

1. 未登录无法执行远程命令

错误信息：

You must login before executing remote commands.
sharecrm auth login

处理方式：

sharecrm auth login

2. 登录状态已失效

错误信息：

提示：登录状态已失效，请重新登录授权。
执行命令：sharecrm auth login

处理方式：重新执行登录。

3. 设备码过期或授权被拒绝

可能会看到类似错误：

  • Device code expired. Please run auth login again.
  • Authorization was denied. Please try again after granting access.

处理方式：重新执行 sharecrm auth login。

4. 缺少认证地址配置

如果 FS_CLI_AUTH_BASE_URL 未配置且构建产物中也没有有效默认值，认证相关命令会失败。

5. Windows secret store 异常

Windows 下会话 secret 读取依赖 powershell.exe 与 DPAPI。若本地 secret 不可读，sharecrm 和 sharecrm help 会按未登录处理；远程命令执行仍需要重新登录或修复本地环境。

开发与测试

npm run build
npm run typecheck
npm run lint
npm test

说明：

  • npm test 会先执行构建，再运行 vitest
  • npm run build:debug 可直接从源码启动 CLI