SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsfeishu-cli-attendance

feishu-cli-attendance

Office & productivity

View repository

Updated 10-16 01:56

About this skill

Feishu attendance data query

Via feishu-cli attendance(alias att) query user attendance clock-in records and statistics, integrating with the Feishu Attendance OpenAPI.

feishu-cli: if not yet installed, please go to riba2534/feishu-cli to get the installation method.

Core Concepts

Tenant Token Restriction (Critical)

  • All commands use tenant_access_token(app identity),no need for feishu-cli auth login。
  • larksuite/oapi-sdk-go v3.5.3 in Attendance.UserTask.Query and Attendance.UserStatsData.Query 's SupportedAccessTokenTypes contains only Tenant, passing in a User Access Token will be directly rejected by the SDK。
  • Permissions are granted to the app via the Feishu Open Platform "App Permission Management" page:
    • attendance:task:readonly(recommended, only queries clock-in and statistics data, cannot write or modify)
    • attendance:task(includes write)
  • Prerequisites for app identity startup:FEISHU_APP_ID + FEISHU_APP_SECRET(environment variable or ~/.feishu-cli/config.yaml）。

Date Format

Accepts YYYY-MM-DD or YYYYMMDD two formats, the CLI internally converts them uniformly to the yyyyMMdd integer required by the OpenAPI.

Span Limit (Critical)

  • user-stats query start-end span ≤ 31 days, exceeding which will be directly rejected locally (no request sent).
  • user-task query has no 31-day span limit(unlike user-stats query , no local date span pre-validation is done), but is still subject to the 50-user limit.

Command Quick Reference

1. Query clock-in records user-task query

feishu-cli attendance user-task query \
    --employee-type <type> --user-ids <ids> \
    --start <date> --end <date> [选项]

Underlying call to POST /open-apis/attendance/v1/user_tasks/query. Returns actual clock-in results for on/off duty (including optional overtime shift segments).

Parameter Type Required Description
--employee-type string - User ID type:employee_id (default) / open_id / user_id / employee_no
--user-ids CSV ✓ User ID list, comma-separated,maximum 50
--start string ✓ Start workday (YYYY-MM-DD or YYYYMMDD)
--end string ✓ End workday (YYYY-MM-DD or YYYYMMDD)
--need-overtime bool - Whether to include overtime shift clock-in results (default false)
--ignore-invalid-users bool - Ignore invalid/no-permission users (default true)
--include-terminated bool - Include resigned employee data (default false)
-o, --output string - text(default) / json

2. Query attendance statistics user-stats query

feishu-cli attendance user-stats query \
    --employee-type <type> --user-ids <ids> --current-user-id <id> \
    --stats-type <daily|month> --start <date> --end <date> [选项]

Underlying call to POST /open-apis/attendance/v1/user_stats_datas/query. Returns aggregated statistical fields such as attendance/late/early leave/leave (attendance days, late count, overtime duration……).

Parameter Type Required Description
--employee-type string - User ID type (same as above, default employee_id）
--stats-type string - daily(daily, default) / month(monthly)
--user-ids CSV ✓ List of user IDs to query,maximum 200
--current-user-id string - User ID initiating the request (required for new system users, corresponds to "Query Statistics Settings"user_id）
--start string ✓ Start date
--end string ✓ End date (span ≤ 31 days)
--locale string - Language:zh / en / ja
--need-history bool - Whether to return historical data (default false)
--current-group-only bool - Show only the current attendance group (default false)
-o, --output string - text(default) / json

Usage Example

# 查询本人最近一周打卡
feishu-cli attendance user-task query \
    --employee-type open_id --user-ids ou_xxxxxxxx \
    --start 2026-05-01 --end 2026-05-18

# 多人 + 加班 + JSON
feishu-cli attendance user-task query \
    --employee-type open_id \
    --user-ids ou_aaa,ou_bbb \
    --start 20260501 --end 20260518 \
    --need-overtime -o json

# 查本人 5 月日度统计
feishu-cli attendance user-stats query \
    --employee-type open_id \
    --user-ids ou_xxxxxxxx --current-user-id ou_xxxxxxxx \
    --stats-type daily --start 2026-05-01 --end 2026-05-31

# 查月度统计 + JSON
feishu-cli attendance user-stats query \
    --employee-type open_id --user-ids ou_xxx --current-user-id ou_xxx \
    --stats-type month --start 2026-05-01 --end 2026-05-31 -o json

# 兼容 alias：att 等价 attendance
feishu-cli att user-task query --user-ids ou_xxx --start 2026-05-01 --end 2026-05-18

Output Fields

user-task query text mode

共 N 条打卡任务:

[i] <姓名> (<user_id>)  日期: YYYY-MM-DD
    考勤组: <group_id>   班次: <shift_id>   打卡记录 ID: <result_id>
    [j] (上下班 / 加班)
        上班: HH:MM  结果: <Normal/Late/Early/Lack/...>  (补充说明)
        下班: HH:MM  结果: <...>                          (补充说明)

⚠ 无效用户 ID (n): id1, id2
⚠ 无权限用户 ID (n): id3, id4

user-stats query text mode

共 N 个用户的统计数据:

[i] <姓名> (<user_id>)
    <统计字段标题>     = <值>
    出勤天数            = 22
    迟到次数            = 1
    请假时长            = 2.5h
    ...

⚠ 无权限用户 (n): id1, id2

JSON mode directly outputs the normalized struct (AttendanceQueryUserTaskResult / AttendanceQueryUserStatsResult) for easy consumption by AI Agents and scripts.

When not to use this skill

In the following scenariosdo notuse feishu-cli attendance; this module only covers the two "query" APIs:

Scenario Alternative
Managing/editing schedules, shift definitions, and attendance groups Feishu Open Platform OpenAPI Explorer, or directly call /open-apis/attendance/v1/shifts、/groups etc.
Approval attendance (leave/overtime request query/approval) feishu-cli approval module
Clock-in correction/manual clock-in OpenAPI /open-apis/attendance/v1/user_task_remedys, not yet wrapped by this CLI
"Query attendance group members" type scenarios OpenAPI /open-apis/attendance/v1/groups/{group_id}
Any scenario requiring write operations (clock-in correction approval, shift modification) Directly call OpenAPI (requires attendance:task write permission)

Common errors and troubleshooting

Symptom Cause Solution
unsupported access token type, only support: Tenant User Token was passed by mistake Remove --user-access-token / FEISHU_USER_ACCESS_TOKEN; this module only uses Tenant
--user-ids 单次最多 50 个 / 200 个 Exceeds local pre-validation limit user-task ≤ 50, user-stats ≤ 200; split into batches if exceeded
--start 到 --end 跨度不能超过 31 天 user-stats only has this local pre-validation (cmd/attendance_user_stats.go:114), user-task is unrestricted Split user-stats into multiple queries, each ≤ 31 days; user-task is not subject to this limit
日期 "xxx" 不是 YYYYMMDD 8 位数字 Incorrect date format Use YYYY-MM-DD or plain 8-digit number YYYYMMDD
99991663 / attendance:task permission error The app has not enabled the attendance scope Feishu Open Platform → App Permission Management → Request attendance:task:readonly and publish a new version
current_user_id is invalid（user-stats） New system users did not pass --current-user-id Add --current-user-id, and keep the value consistent with the target user in user-ids
invalid_user_ids / unauthorized_user_ids is not empty Some user-ids do not exist or the app has no permission for that user Check the user-id type and the app's visibility scope settings

Permission Requirements

Command Required scope (tenant level)
attendance user-task query attendance:task:readonly(recommended) or attendance:task
attendance user-stats query attendance:task:readonly(recommended) or attendance:task

After the permission is enabled on the Feishu Open Platform "App Permission Management" pagethe app must publish a new versionfor it to take effect; attendance data involves employee privacy, and enterprise administrators usually require approval before granting access.