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
Read and edit Lark/Feishu Docx & Wiki documents via CLI — fetch, create, update, and manage media attachments.
lark-base
Manage Lark Base (multi-dimensional tables): create tables, fields, records, views, formulas, forms, dashboards, workflows, and roles.
lark-im
Lark/Feishu IM skill: send messages, manage group chats, download files, and handle interactive cards via lark-cli
lark-drive
Manage Lark/Feishu Drive files and folders: upload, download, import, organize, comment, and control permissions.
lark-shared
Manage Lark CLI auth, identity, permissions, and scopes for coding agents like Claude Code and Cursor
lark-calendar
Manage Lark calendar events and meeting rooms: view, create, update events, check availability, and book rooms.