CLI 使用帮助

HAP CLI 把 HAP 的后端能力封装到命令行里，覆盖三类场景：

协作沟通 — 查通讯录/部门、收发单聊和群聊消息、发动态、管日程
应用数据 — 读写工作表记录（增删改查、筛选、透视统计）、跑工作流、处理审批待办、操作自定义页面和角色权限、上传文件
应用修改 — 对已有应用做精确的局部修改（加字段、改视图、调流程等）

配合 AI 使用，可以用自然语言驱动整个 HAP 平台的操作。

安装

pip install hap-cli

使用前提：开启组织的 CLI 访问权限

只有组织开启了 CLI 访问权限，hap 才能访问该组织的数据。请组织管理员前往「组织管理后台 → 安全 → 数据与访问 → CLI 访问策略」开启允许访问开关。未开启时命令会被拦截，管理员开启后直接重跑命令即可。

可用 hap auth list-my-orgs 查看各组织的开启状态（CLI:on/off）。

# 明道云 SaaS 默认环境
hap auth login

# 显式指定环境
hap auth login mingdao                       # 生产
hap auth login nocoly                        # Nocoly SaaS
hap auth login https://hap.example.com       # 私有部署

# 非交互式（脚本 / headless 服务器）
hap auth login https://your-server.com --token YOUR_TOKEN

浏览器流程会打开 HAP 登录页并捕获令牌。如果 CLI 收不到回调（无 GUI、网络受限），中断命令即可回退到粘贴登录页显示的令牌。

hap auth whoami        # 当前用户、当前环境/账号与当前组织
hap auth logout        # 登出当前账号

多环境 / 多账号

可同时授权多个环境（Mingdao SaaS、Nocoly、私有部署）与多个账号，各存成一个具名档案，长期共存、随时切换：

hap auth login mingdao --profile work-prod        # 登录并起名保存
hap auth login https://hap.example.com --profile onprem
# 省略 --profile 时按登录地址自动起名，登录新环境不会覆盖已保存的

hap auth accounts                  # 列出所有环境/账号，当前的带 *
hap auth use work-prod             # 切换当前使用的环境/账号
hap --profile onprem app list      # 只让这一条命令临时用某个环境/账号
HAP_PROFILE=onprem hap app list    # 整个终端会话默认用某个环境/账号

hap auth logout -p onprem          # 登出指定账号
hap auth logout --all              # 登出全部账号

档案选择优先级：--profile > 环境变量 HAP_PROFILE > 当前档案。

选定组织和应用

hap auth list-my-orgs                     # 当前组织以 * 标出
hap auth set-current-org ORG_ID           # 切换默认组织
hap app list                              # 使用默认组织
hap app list --org-id ORG_ID              # 显式覆盖

# 设置默认应用，后续命令省略 --app-id 即可
hap app select APP_ID
hap app unselect                          # 清除默认应用

hap auth set-current-org 切换默认组织；切换到不同组织时会同时清除默认应用（应用从属于组织）。之后用 hap app select 重新选择默认应用。

浏览工作表与记录

hap app info APP_ID                          # 分组、工作表、自定义页面一览
hap worksheet list                           # 默认应用下的工作表
hap worksheet info WORKSHEET_ID              # 完整结构（设置 + 字段）
hap worksheet field-types                    # 字段类型常量参考
hap worksheet record list WORKSHEET_ID --page-size 10

JSON 输出

hap --json worksheet record list WORKSHEET_ID

所有命令都支持 --json，便于脚本处理。

默认应用与组织

任何需要 --app-id 的命令解析顺序：

命令显式传入的 --app-id
hap app select APP_ID 保存的默认应用
仍为空时报错并提示设置默认应用

hap auth set-current-org 切换默认组织；切到不同组织时会同时清除默认应用。

REPL 模式

hap repl
hap> worksheet record list WORKSHEET_ID
hap> --json workflow list
hap> approval todo-count
hap> quit

REPL 内省略 hap 前缀；以 --json 起头切到 JSON 输出。

命令一览

每层都可以用 hap <group> --help 查看完整子命令。

auth — 认证与会话

命令	说明
`auth login [SERVER]`	浏览器登录（`--token` 非交互；`--profile NAME` 存为具名档案；`--force` 重指向已有名字）
`auth accounts`	列出所有环境/账号，当前标 `*`
`auth use NAME`	切换当前使用的环境/账号
`auth logout`	登出当前账号（`-p NAME` 指定，`-a/--all` 全部）
`auth whoami`	当前用户、当前环境/账号与当前组织
`auth list-my-orgs`	当前账号所属组织（当前标 `*`，显示 CLI 访问权限开关状态 `CLI:on/off`）
`auth set-current-org ORG_ID`	切换默认组织（切到不同组织时清除默认应用）

app — 应用管理

命令	说明
`app list`	列出组织下的应用（默认应用以 `*` 高亮）
`app list-managed`	当前用户作为管理员的应用
`app info APP_ID`	应用详情（含分组、工作表、自定义页面）
`app create / update / delete`	应用生命周期
`app select APP_ID` / `app unselect`	设置/清除默认应用
`app create-section / edit-section / delete-section`	分组管理
`app sort-sections / sort-worksheets`	重排分组 / 分组内工作表顺序
`app create-item`	批量创建空白工作表/自定义页面
`app backup / export / exports / backup-logs`	备份与导出
`app usage / logs`	使用统计与操作日志
`app role …`	角色 CRUD、权限、成员、leave-all、申请
`app optionset …`	选项集 CRUD 与跨应用迁移
`app knowledge list / search`	应用知识库

worksheet — 工作表、视图、自定义动作、统计图

命令	说明
`worksheet list / info / fields / field-types`	查看结构
`worksheet create / update / copy / delete`	工作表生命周期
`worksheet rules / save-rule`	业务规则
`worksheet switches / edit-switch`	功能开关
`worksheet form-settings / save-form-settings`	表单提交/高级设置
`worksheet custom-actions / create-custom-action / delete-custom-action`	自定义动作按钮
`worksheet create-chart`	创建统计图
`worksheet view list / info / create / copy / delete / sort`	视图管理

worksheet record — 记录 CRUD

命令	说明
`worksheet record list / get`	查询/读取
`worksheet record create / update / delete`	单行 CRUD
`worksheet record batch-create / batch-update`	批量操作（关联/子表值均正常写入）
`worksheet record relations / share-link`	关联记录与分享链接
`worksheet record discussions / add-discussion / delete-discussion`	讨论
`worksheet record logs`	单条记录变更日志
`worksheet record pivot / bottom-stats`	透视表与底部汇总

workflow — 工作流与节点

命令	说明
`workflow list / get / structure / history / groups / stats`	查看
`workflow create / update / copy / move / delete`	生命周期
`workflow publish / rollback`	版本管理
`workflow trigger / trigger-pbp`	手动触发
`workflow config-get / config-set`	全局配置
`workflow create-approval / update-approval / delete-approval`	审批容器
`workflow node …`	节点 CRUD、batch-add / batch-update / batch-delete、test-code / test-webhook / test-ai、controls、types、代码模板

approval — 审批与待办

命令	说明
`approval todo / todo-count / todo-filters / archived`	待办与归档
`approval get / get-by-row / list-by-row / work-item / operations / op-history / history / history-detail`	实例状态
`approval approve / reject / submit / sign / forward / urge`	审批动作
`approval revoke / terminate / restart / retry`	实例生命周期
`approval batch / retry-batch / end-batch`	批量动作
`approval list-types`	枚举参考
`approval delegation create / list / list-by-company / list-by-principals / update`	审批委托

custom-page — 自定义页面

命令	说明
`custom-page info / save / update-config`	读写布局
`custom-page create / rename / copy / delete`	生命周期
`custom-page component-types`	组件参考

contact — 通讯录与联系人

命令	说明
`contact search / resolve`	关键词搜索 / 解析 accountId
`contact friends / friend-requests`	通讯录
`contact add-friend / accept-friend / reject-friend / ignore-friend / remove-friend`	好友管理

department — 部门

命令	说明
`department list / tree / info / members / search`	部门查询

post — 动态与帖子

命令	说明
`post list / search / get`	阅读
`post create / update / delete`	发帖 / 编辑 / 删除
`post comment / comments / comment-delete`	评论
`post like / likes / favorite`	点赞 / 收藏
`post pin / unpin / pinned`	置顶
`post topics`	话题标签

calendar — 日历与日程

命令	说明
`calendar list / get / create / update / delete`	日程生命周期
`calendar categories`	内置分类
`calendar add-member / remove-member`	成员管理

chat — 聊天与消息

命令	说明
`chat list`	最近会话
`chat messages`	单聊 / 群聊 / 收件箱（系统、应用、工作流等）
`chat files`	聊天中分享的文件
`chat send`	向一个或多个用户发送纯文本消息
`chat group-info`	群组信息
`chat card-detail`	解析消息中嵌入的卡片引用

region — 行政区划

命令	说明
`region get`	通过 `--id` 精确查或 `--search` 关键词模糊查

icon — 内置图标目录

命令	说明
`icon search`	按中英文关键词搜索图标（多关键词取并集，命中越多排越前；命中不足 10 个时随机补足推荐）
`icon list [-n SIZE] [-p PAGE]`	分页列出图标及其关键词（默认每页 50 个）

upload — 文件上传

命令	说明
`upload [SOURCES...]`	上传本地路径或 http(s) 直链到文件存储，返回文件描述符（fileID/key/url/serverName/filePath/fileName/fileExt/originalFileName/fileSize）

config — 本地 CLI 配置

命令	说明
`config show`	显示 CLI 配置摘要
`config completion [bash\|zsh\|fish] [--install]`	启用 `<Tab>` 补全
`config language [LANG]`	切换显示语言（`en` / `zh-Hans` / `zh-Hant` / `ja`）
`config log on / off / status`	日志开关与状态
`config log level LEVEL`	设置日志级别（`DEBUG/INFO/WARNING/ERROR/CRITICAL`）
`config log view [--lines N] [--no-follow]`	跟踪日志文件

update — 升级 CLI

命令	说明
`update`	检查 PyPI 最新版本，有新版则用安装时的工具（pip / pipx / uv）原地升级
`update --check`	只检查是否有新版本，不安装

示例

# 创建记录
hap worksheet record create WORKSHEET_ID -f "c001=value1" -f "c002=value2"

# 搭工作流
hap workflow create --name "My Flow" --app-id APP_ID
hap workflow node add PROCESS_ID --type 4 --name "Manager Approval"
hap workflow node save PROCESS_ID NODE_ID --config '{"accounts":[...]}'
hap workflow publish PROCESS_ID
hap workflow trigger PROCESS_ID --source-id ROW_ID

# 审批
hap approval todo --type 4
hap approval approve INSTANCE_ID --opinion "OK"
hap approval reject INSTANCE_ID --opinion "需修订"
hap approval batch --action 4 -s ID1 -s ID2

# 角色
hap app role list
hap app role add-member ROLE_ID -u USER_ID

# 知识库检索
hap app knowledge search --keyword "新人入职" --mode hybrid

这篇文档对你有帮助吗？

安装​

使用前提：开启组织的 CLI 访问权限​

登录​

多环境 / 多账号​

选定组织和应用​

浏览工作表与记录​

JSON 输出​

默认应用与组织​

REPL 模式​

命令一览​

auth — 认证与会话​

app — 应用管理​

worksheet — 工作表、视图、自定义动作、统计图​

worksheet record — 记录 CRUD​

workflow — 工作流与节点​

approval — 审批与待办​

custom-page — 自定义页面​

contact — 通讯录与联系人​

department — 部门​

post — 动态与帖子​

calendar — 日历与日程​

chat — 聊天与消息​

region — 行政区划​

icon — 内置图标目录​

upload — 文件上传​

config — 本地 CLI 配置​

update — 升级 CLI​

示例​

安装