lark-okr

okr (v2)

CRITICAL — Before starting, you MUST first use the Read tool to read ../lark-shared/SKILL.md, which contains authentication and permission handling

Identity: OKR operations use by default --as user(when viewing the current user's/superior's/subordinate's OKRs). Also supports --as bot to view others' OKRs (requires corresponding permissions).

Quick Decision

User requirement	Operation path	Reference document
View own/others' OKRs	Get user ID -> +cycle-list -> +cycle-detail -> query metrics/progress records as needed	cycle-list, cycle-detail, indicators, progress-list
Write a set of OKRs for yourself	Prefer to use +batch-create to create an Objective/KR skeleton	batch-create, contentblock
Add only one O or a single KR	Use +create	create
Edit content/notes/deadline	Use +patch	patch
Modify OKR score	Use +patch --scoreonly when the user explicitly says "score", "rating", "grade", or "score"; score is not progress/completion	patch
Adjust order or weight	Use +reorder / +weight	reorder, weight
Update numeric progress/completion	Use +indicator-updatefor percentages or numbers without units; to change units/target values, query the metric then use indicators patch	indicator-update, indicators
Write text progress	Use +progress-create; if there is both text and numbers, percentages or default units can use --progress-percent to update uniformly, and non-percentage units update the quantitative metric	progress-create, progress-list, progress-update
Align objectives	Handle directly according to the alignment relationship workflow	alignments
Query/create/modify/resolve OKR comments	To get an aggregate of all comments under a cycle, use +comment-detail; to query a single O/KR/progress or to query only cycle-level global comments, use +comment-list；	comment, comment-create, comment-solve-reopen

Handle categories only when the user explicitly requests categorization, or when creating an Objective returns invalid parameters and there is suspicion that the tenant has forcibly enabled categorization: use lark-cli okr categories list --params '{"owner_type":"user","page_size":100}' --as user to check available categories, and select a semantically appropriate andenabled=true category ID; categories can be adjusted later, so there is no need to stop and wait for user confirmation.

To get the current user, use contact +get-user; to look up others by name/email, use contact +search-user, and after obtaining open_id , then query the OKR.

lark-cli contact +search-user --query "张三" --has-chatted --as user

Most commonly used OKR command examples:

# 查用户周期，再用周期 ID 查详情
lark-cli okr +cycle-list --user-id "ou_xxx" --as user
lark-cli okr +cycle-detail --cycle-id 7000000000000000001 --as user

# 批量创建 Objective/KR
lark-cli okr +batch-create \
  --cycle-id 7000000000000000001 \
  --input '[{"text":"提升产品用户体验","notes":"关注核心流程和用户反馈","krs":[{"text":"核心流程满意度达到 4.8 分"}]}]' \
  --as user

# 更新数字进度/完成度
lark-cli okr +indicator-update \
  --level key-result \
  --id 7000000000000000003 \
  --value 75 \
  --as user

Do not mix up score and progress: when the user says "progress", "completion", or "currently at 75%", they are usually changing a quantitative metric or writing a progress record, not changing score. Only when explicitly requesting to modify the OKR score/rating/grade should you use +patch --score；score values range from 0-1, with at most one decimal place.

Progress judgment rules: when the user says "progress" or "completion", first determine whether it is a quantitative number. Numeric progress usually corresponds to a quantitative metric; non-quantifiable text corresponds to a progress record. To modify metric units, see lark-okr-indicators.md

Shortcuts (recommended to use first)

Shortcuts are high-level wrappers for common operations (lark-cli okr +<verb> [flags]). For operations with Shortcuts, use them first.

Shortcut	Description
+cycle-list	Paginated retrieval of the OKR cycle list for a specific user; you can use --time-range to post-filter the current page
+cycle-detail	Retrieve the content of all objectives and key results in a specific OKR
+create	Create a single Objective (with optional notes), or add a new KR to an existing Objective
+progress-list	Paginated retrieval of the progress record list for an objective or key result
+progress-get	Retrieve a single OKR progress record by ID
+progress-create	Create a progress record for an objective or key result
+progress-update	Update the content of the progress record with the specified ID
+progress-delete	Delete the progress record with the specified ID (irrecoverable)
+upload-image	Upload an image for use in the rich text content of an OKR progress record
+batch-create	Batch create Objectives (with optional notes) and KRs
+reorder	Adjust the order of an Objective or KR
+weight	Adjust the weight of an Objective or KR
+indicator-update	Update the current progress metric of an Objective or KR. For more complex quantitative metric operations, see Quantitative Metric Management
+patch	Partially update an Objective or KR (content, notes, score, deadline)
+comment-detail	Retrieve all comments for Cycle/Objective/KeyResult/Progress under a cycle
+comment-list	Paginated retrieval of comments under a single OKR entity
+comment-get	Retrieve details of a single comment
+comment-create	Create a new comment or reply to an existing comment (only supports --as user)
+comment-patch	Modify comment content (only supports --as user)
+comment-delete	Permanently delete a single comment (only supports --as user)
+comment-solve	Resolve a comment or highlighted-text comment thread (only supports --as user)
+comment-reopen	Reopen a comment or highlighted-text comment thread (only supports --as user)

Create Scenario Selection

• For single creation, prefer +create: suitable for creating one Objective, or adding one KR to an existing Objective.
• For batch creation, use +batch-create: suitable for creating multiple Objectives at once, with multiple KRs optionally attached at the same time.
• If you only need to modify the content, notes, score, or deadline of an existing Objective / KR, use +patch。

Format Description

• OKR 业务实体 Retrieve the OKR entity structure, definitions, and relationships to help you better use OKR features
• ContentBlock 富文本格式 — Explanation of the rich text format used by the Content/Note fields in Objective/KeyResult/Progress, and further explanation of the simplified SemiPlainContent format.
• Strongly recommended Before operating on OKRs, readOKR 业务实体to understand the basic concepts

API Resources

alignments

• delete — Delete alignment relationship
• get — Retrieve alignment relationship

Operation Guide: OKR Alignment Relationship Management includes the complete list/create/delete workflow

categories

• list — Batch retrieve categories

cycles

• list — Batch retrieve user cycles

cycle.objectives

• list — Batch retrieve objectives under a user cycle

indicators

• patch — Update quantitative metrics

Operation Guide: OKR Quantitative Metric Management includes the complete workflow for querying and patch-updating objective/KR metrics

key_results

• delete — Delete key result
• get — Retrieve key result
• patch — Update key result

key_result.indicators

• list — Retrieve the quantitative metric of a key result

Operation Guide: OKR Quantitative Metric Management

objectives

• delete — Delete objective
• get — Retrieve objective
• key_results_position — Update the positions of all key results
  • The request must carry the IDs of all key results under the corresponding period, otherwise parameter validation will fail. Rearrange the key results in the order of the passed-in key result IDs.
• key_results_weight — Update the weights of all key results
  • Similar to objectives_weight, the request must simultaneously modify the weights of all key results under the corresponding objective, and the sum of all weight values must equal 1, otherwise parameter validation will fail.
• patch — Update objective

objective.alignments

• create — Create alignment relationship
  • Alignment does not allow aligning an objective with itself, and the periods of the initiating objective and the aligned objective must overlap in time, otherwise parameter validation will fail.
• list — Batch retrieve alignment relationships under an objective

objective.indicators

• list — Retrieve the quantitative metrics of an objective

objective.key_results

• list — Batch retrieve key results under an objective

Not within the scope of this skill

• To-do task management → Use lark-task
• Scheduling → Use lark-calendar
• Performance evaluation → Use lark-openapi-explorer to find the native interface