people-cli

中文版 | English

飞书 People 域官方 CLI 工具。people-cli 当前覆盖 CoreHR 等 People 域能力，并提供少量配套工作流辅助命令，例如 Drive 文件上传下载。

安装 · 认证 · 命令 · 进阶用法 · 贡献

为什么选 people-cli？

• 聚焦 People 域 — 一套 CLI 覆盖 CoreHR，以及周边工作流辅助能力
• Shortcut 优先，API 完整 — 常见场景优先走高级快捷命令，复杂需求可下钻到服务命令和通用 API
• AI 友好 — 结构化输出和稳定命令形态，适合 AI Agent 与自动化集成
• 上手快 — 引导式配置、按域授权、Schema 自省，缩短从安装到首次成功调用的路径
• 安全可控 — 输入防注入、终端输出净化、系统原生密钥链存储凭证
• 开源可扩展 — MIT 协议，适合本地开发、自动化脚本和二次封装

功能

| 类别 | 能力 | | --- | --- | | corehr | 部门查询、员工搜索、员工基本信息、任职信息、待入职查询、编制查询、名称转 ID 快捷命令 | | 辅助能力 | Drive 文件上传下载等周边工作流辅助命令 |

安装与快速开始

环境要求

开始之前，请确保具备以下条件：

• Go v1.23+ 和 Python 3（源码构建需要）

快速开始

安装

从源码编译安装：

# Clone 仓库
git clone https://code.byted.org/people/cli.git
cd cli

# 编译并安装
make install

# 验证安装
people-cli --version

配置与使用

# 1. 配置应用凭证（仅需一次，交互式引导完成）
people-cli config init

# 2. 按 People 域登录授权
people-cli auth login --domain corehr --recommend

# 3. 开始使用快捷命令
people-cli corehr +prehire-search --format table

认证

| 命令 | 说明 | | --------------- | -------------------------------------------------- | | auth login | OAuth 登录，支持交互式选择或命令行参数指定 scope | | auth logout | 登出并删除已存储的凭证 | | auth status | 查看当前登录状态和已授权的 scope | | auth check | 校验指定 scope（exit 0 = 有权限，1 = 缺失） | | auth scopes | 列出应用的所有可用 scope | | auth list | 列出所有已认证的用户 |

# 交互式登录
people-cli auth login

# 按 People 域授权
people-cli auth login --domain corehr --recommend

# 精确 scope
people-cli auth login --scope "corehr:department:read"

# Agent 模式：立即返回验证 URL，不阻塞
people-cli auth login --no-wait
# 稍后恢复轮询
people-cli auth login --device-code <DEVICE_CODE>

# 身份切换：以用户或机器人身份执行命令
people-cli corehr department list --as user --params '{"page_size":50}'

命令调用体系

CLI 提供三种粒度的调用方式，覆盖从快速操作到完全自定义的全部场景：

1. 快捷命令（Shortcuts）

以 + 为前缀，对人类与 AI 友好化封装，内置智能默认值、表格输出和 dry-run 预览。

# 搜索待入职员工
people-cli corehr +prehire-search --format table

# 查询员工基本信息
people-cli corehr +employee-basic-info-query --format pretty

2. API 命令

从飞书 OAPI 元数据自动生成，经过评测与准入筛选。

# 获取部门列表
people-cli corehr department list --params '{"page_size":50}'

# 查询异动记录
people-cli corehr job_change search --params '{"page_size":10}'

3. 通用 API 调用

直接调用任意飞书开放平台端点。

people-cli api POST /open-apis/corehr/v2/common/query_id_by_name --data '{"business_scene":"team","target_object_api_name":"department","query_name":"研发部"}'

进阶用法

输出格式

--format json      # 完整 JSON 响应（默认）
--format pretty    # 人性化格式输出（适用于部分命令，如 shortcuts / schema）
--format table     # 易读表格
--format ndjson    # 换行分隔 JSON（适合管道处理）
--format csv       # 逗号分隔值

分页

--page-all                  # 自动翻页获取所有数据
--page-limit 5              # 最多获取 5 页
--page-delay 500            # 每页请求间隔 500ms

Dry Run

对可能产生副作用的命令，建议先用 --dry-run 预览请求：

people-cli api POST /open-apis/corehr/v2/common/query_id_by_name --data '{"business_scene":"team","target_object_api_name":"department","query_name":"研发部"}' --dry-run

Schema 自省

使用 schema 查看任意 API 方法的参数、请求体、响应结构、支持身份和 scopes：

people-cli schema
people-cli schema corehr.job_change.search --format pretty

配置管理

# 初始化配置
people-cli config init

# 查看当前配置
people-cli config show

# 设置默认身份
people-cli config default-as user

# 删除配置
people-cli config remove

健康检查

# 检查配置、认证和连通性
people-cli doctor

# 离线检查（跳过网络）
people-cli doctor --offline

安全与风险提示（使用前必读）

本工具可供 AI Agent 调用以自动化操作飞书开放平台，存在模型幻觉、执行不可控、提示词注入等固有风险；授权飞书权限后，AI Agent 将以您的用户身份在授权范围内执行操作，可能导致敏感数据泄露、越权操作等高风险后果，请您谨慎操作和使用。

为降低上述风险，工具已在多个层面启用默认安全保护，但上述风险仍然存在。我们强烈建议不要主动修改任何默认安全配置；一旦放开相关限制，上述风险将显著提高，由此产生的后果需由您自行承担。

我们建议您将对接本工具的飞书机器人作为私人对话助手使用，请勿将其拉入群聊或允许其他用户与其交互，以避免权限被滥用或数据泄露。

请您充分知悉全部使用风险，使用本工具即视为您自愿承担相关所有责任。

贡献

欢迎社区贡献！如果你发现 bug 或有功能建议，请提交 Issue 或 Merge Request。

对于较大的改动，建议先通过 Issue 与我们讨论。

相关项目

• people-cli-registry — API 注册表生成器，为 people-cli 提供 People 域 API 元数据和命令生成配置

许可证

本项目基于 MIT 许可证 开源。 该软件运行时会调用飞书开放平台的 API，使用这些 API 需要遵守如下协议和隐私政策：

• 飞书用户服务协议
• 飞书隐私政策
• 飞书开放平台独立软件服务商安全管理运营规范