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 --as userby default (when viewing the current user's/superior's/subordinate's OKRs). Also supports --as bot to view others' OKRs (requires corresponding permissions).

Quick Decisions

User Need	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 using `+batch-create` to create the Objective/KR skeleton	`batch-create`, `contentblock`
Add only one O or a single KR	Use `+create`	`create`
Edit content/notes/due date	Use `+patch`	`patch`
Modify OKR score	Use `+patch --score`only when the user explicitly says "score", "rating", "grading", or "score"; score is not progress/completion	`patch`
Adjust order or weight	Use `+reorder` / `+weight`	`reorder`, `weight`
Update numeric progress/completion	For percentages or numbers without units, use `+indicator-update`; to change units/target values, query metrics 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` for unified changes; for 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 all comment aggregations under a period, use `+comment-detail`; to query a single O/KR/progress or query only period-global comments, use `+comment-list`；	`comment`, `comment-create`, `comment-solve-reopen`

Categories are handled only when the user explicitly requests categorization, or when creating an Objective returns invalid parameters and there is suspicion that the tenant has forced categories on: use lark-cli okr categories list --params '{"owner_type":"user","page_size":100}' --as user to query available categories, and select a semantically appropriate category withenabled=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 query others by name/email, use contact +search-user, and after obtaining open_id , then query OKRs.

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 asked to modify the OKR score/rating/grading should you use +patch --score；score ; the value range is 0-1, with at most one decimal place.

Progress determination 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 change a metric unit, see lark-okr-indicators.md

Shortcuts (recommended to use first)

Shortcut is a high-level wrapper for common operations (lark-cli okr +<verb> [flags]). For operations with a Shortcut, use it first.

Shortcut	Description
`+cycle-list`	Get a specific user's OKR period list with pagination; you can use `--time-range` to post-filter the current page
`+cycle-detail`	Get the content of all objectives and key results in a specific OKR
`+create`	Create a single Objective (can include notes), or add a KR to an existing Objective
`+progress-list`	Get a paginated list of progress records for an objective or key result
`+progress-get`	Get 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 Objectives or KRs
`+weight`	Adjust the weight of Objectives or KRs
`+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`	Get all comments under Cycle/Objective/KeyResult/Progress for a cycle
`+comment-list`	Get comments under a single OKR entity with pagination
`+comment-get`	Get 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 using +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, and can optionally include multiple KRs.
If you only need to modify the content, notes, score, or deadline of an existing Objective / KR, use +patch。

Format description

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

API Resources

alignments

delete — Delete alignment relationship
get — Get alignment relationship

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

cycles

list — Batch get user cycles

cycle.objectives

list — Batch get objectives under user cycles

indicators

patch — Update quantitative metric

Operation guide: OKR Quantitative Metric Management includes the complete workflow for querying objective/KR metrics and patch updates

key_results

delete — Delete key result
get — Get key result
patch — Update key result

key_result.indicators

list — Get the quantitative metrics of a key result

Operation guide: OKR Quantitative Metric Management

objectives

delete — Delete objective
get — Get objective
key_results_position — Update the positions of all key results
- The request must carry the IDs of all key results under the corresponding cycle, 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, in the request you 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 to itself, and the cycle times of the initiating objective and the aligned objective must overlap; otherwise parameter validation will fail.
list — Batch retrieve alignment relationships under an objective

objective.indicators

list — Retrieve 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 Find native APIs