lark-contact
larksuite/cli
Resolve Lark/Feishu names & emails to open_id, or look up user details by open_id
What is lark-contact?
lark-contact provides two-way user identity resolution for Feishu/Lark: search employees by name or email to get their open_id, or reverse-lookup a known open_id to retrieve name, department, email, contact info, personal status, and bio. It handles both user-identity and bot-identity paths with distinct commands for each. Scope is limited to individual user lookup — department trees, org charts, and bulk department listing are out of scope.
- Search employees by name or email to resolve their open_id (user identity only)
- Look up a user's profile by open_id, returning name, department, email, and contact details
- Retrieve personal status and bio/signature for multiple users in a batch query
- Supports both user identity and bot identity paths with separate commands
- Handles cross-tenant users with appropriate empty-field fallback behavior
- Provides schema inspection via lark-cli schema for exploring available parameters
How to install lark-contact
npx skills add null --skill lark-contact- lark-cli must be installed and available in PATH
- Valid Feishu/Lark credentials configured for user identity and/or bot identity
- Appropriate contact visibility permissions (41050 errors indicate insufficient scope)
- Admin may need to adjust visibility scope for cross-department or bot lookups
How to use lark-contact
- 1.Determine whether you are operating under user identity or bot identity — commands differ per identity
- 2.To find a user by name (user identity): run `lark-cli contact +search-user --query "<name>" --as user`
- 3.To look up a user by open_id (bot identity): run `lark-cli contact +get-user --user-id <open_id>`
- 4.To look up yourself (user identity): run `lark-cli contact +get-user` or `+search-user --user-ids me`
- 5.To batch-query personal status/signature: inspect schema first with `lark-cli schema contact.user_profiles.batch_query`, then call the command with appropriate params
- 6.If search returns multiple candidates, present the list to the user for selection before proceeding with any action
- 7.Use the resolved open_id with lark-im for messaging or lark-calendar for scheduling — do not re-query contact unnecessarily
- 8.If you encounter 41050 Permission denied, switch identity or ask an admin to adjust visibility scope
Use cases
- Find a colleague's open_id by name before sending them a message via lark-im
- Resolve an email address to an open_id for calendar invites
- Batch-query personal status and bio signatures for a list of known open_ids
- Look up your own user profile details
- Confirm the correct user when a name search returns multiple candidates before taking action
- Developers building Feishu/Lark automation workflows that need user identity resolution
- Agents orchestrating multi-step tasks like messaging or scheduling that start from a person's name
- Teams querying employee contact details or status programmatically
- Bot integrations that need to resolve open_ids to human-readable user info
lark-contact FAQ
No. Name/email search is only supported under user identity. Bot identity only supports lookup by a known open_id via +get-user.
Present all candidates to the user and ask them to confirm the correct person before proceeding with any action that has side effects (e.g., sending a message or scheduling a meeting).
Feishu enforces visibility rules for cross-tenant users (is_cross_tenant=true), which causes most business fields to return empty strings. Handle this with null/empty value fallbacks in downstream logic.
No. Department traversal, listing employees by department, and org charts are out of scope. Use lark-openapi-explorer to find the appropriate native OpenAPI endpoints for those needs.
open_id is the default. +get-user also accepts --user-id-type union_id or user_id. +search-user only accepts open_id.
Full instructions (SKILL.md)
Source of truth, from larksuite/cli.
name: lark-contact version: 1.0.0 description: "飞书 / Lark 通讯录:按姓名 / 邮箱解析成 open_id,或按 open_id 反查姓名 / 部门 / 邮箱 / 联系方式 / 个人状态 / 签名。当用户提到某人姓名要下一步发消息 / 排日程,或拿到 open_id 想查具体信息时使用。不负责部门树遍历、按部门列员工、组织架构图,这类需求走原生 OpenAPI。" metadata: requires: bins: ["lark-cli"] cliHelp: "lark-cli contact --help"
选哪个命令
user 身份和 bot 身份是两条完全独立的路径。先确定当前身份,再按下表选命令:
| 想做什么 | user 身份 | bot 身份 |
|---|---|---|
| 按姓名 / 邮箱搜员工拿 open_id | +search-user | 不支持 |
| 已知 open_id 取他人资料 | +search-user --user-ids <id> | +get-user --user-id <id> |
| 查看自己 | +get-user 或 +search-user --user-ids me | 不支持 |
| 查同事的个人状态 / 签名 | user_profiles batch_query | 不支持 |
已知 open_id 只是想发消息 / 排日程,不必经过 contact —— 直接 lark-im / lark-calendar。
典型场景
找张三给他发消息:先搜,确认 open_id,再发:
lark-cli contact +search-user --query "张三" --has-chatted --as user
lark-cli im +messages-send --user-id ou_xxx --text "Hi!"
批量查同事的个人状态 / 个性签名(先用 schema 看参数)。
lark-cli schema contact.user_profiles.batch_query
lark-cli contact user_profiles batch_query \
--params '{"user_id_type":"open_id"}' \
--data '{"user_ids":["ou_xxx","ou_yyy"],"query_option":{"include_personal_status":true,"include_description":true}}' \
--as user
搜索命中多条且后续操作有副作用(发消息、邀请会议等),把候选列给用户挑;不要擅自选第一条。
注意事项
- 41050 / Permission denied 受当前身份的可见范围限制(两条命令都可能遇到)。换 bot 身份或让管理员调整可见范围,细节见
lark-shared。 - 跨租户用户(
is_cross_tenant=true)多数业务字段为空字符串,这是飞书可见性规则,下游做空值兜底。 - ID 类型:默认
open_id。+get-user可改--user-id-type union_id|user_id;+search-user只接受open_id。
不在本 skill 范围
- 发消息 / 查聊天记录 →
lark-im - 排日程 / 邀请会议 →
lark-calendar - 部门树 / 按部门列员工 / 组织架构 →
lark-openapi-explorer查找原生接口
Related skills
More from larksuite/cli and the wider catalog.
lark-doc
飞书云文档（Docx / Wiki 文档）：读取和编辑飞书文档内容。当用户给出文档 URL 或 token，或需要查看、创建、编辑文档、插入或下载文档图片附件时使用。文档中嵌入的电子表格、多维表格、画板，先用本 skill 提取 token 再切到对应 skill。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill；路由依据是 URL 路径模式和 token，而不是域名。不负责文档评论管理，也不负责表格或 Base 的数据操作。
lark-base
飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、workflow、角色权限；遇到 Base/多维表格/bitable 或 /base/ 链接时使用。文件导入转 lark-drive，认证/授权转 lark-shared。
lark-im
飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复、发送应用内/短信/电话加急、发送和处理交互卡片（Interactive Card）、监听卡片按钮回调（card.action.trigger）。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据、管理 Feed 置顶（添加/移除/查询置顶会话）、管理标签数据、处理卡片回调时使用。
lark-drive
飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。
lark-shared
Use for lark-cli setup/auth tasks: auth login/status/logout, user vs bot identity, business-domain permissions (--domain, including all/docs/drive), missing scopes, revoking authorization, or handling _notice JSON.
lark-calendar
飞书日历：管理日历日程和会议室。查看/搜索日程、创建/更新日程、管理参会人、查询忙闲和推荐时段、预定会议室。当用户需要查看日程安排、创建/修改会议、查询/预定会议室时使用。不负责：查询过去的视频会议记录（走 lark-vc）、待办任务（走 lark-task）。