---
title: "Todo skill"
description: "Query, create, update, delete, and track WeCom work items through wecom-cli."
---

The `wecomcli-todo` skill gives the AI full control over your WeCom todo items. It can list your tasks, retrieve their full content, create new items with assignees and reminders, update existing ones, delete them, and change your per-item status (accept, reject, or mark complete).

<Note>
  `get_todo_list` returns only summary information (IDs and status). The AI always calls `get_todo_detail` immediately after to fetch the actual content before showing you anything.
</Note>

## Available operations

### get_todo_list

Returns a paginated list of your todos, filtered by creation or reminder time.

```bash
wecom-cli todo get_todo_list '{"create_begin_time": "2026-01-01 00:00:00", "create_end_time": "2026-03-31 23:59:59", "limit": 20}'
```

**Key parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `create_begin_time` | string | Filter by creation start time (`YYYY-MM-DD HH:mm:ss`). |
| `create_end_time` | string | Filter by creation end time. |
| `remind_begin_time` | string | Filter by reminder start time. |
| `remind_end_time` | string | Filter by reminder end time. |
| `limit` | number | Max results per page. Default `10`, max `20`. |
| `cursor` | string | Pagination cursor. Omit on the first request. |

If `has_more` is `true` in the response, the AI tells you there are more todos and asks whether to continue.

### get_todo_detail

Returns full details — content, assignees, and status — for up to 20 todos at once.

```bash
wecom-cli todo get_todo_detail '{"todo_id_list": ["TODO_ID_1", "TODO_ID_2"]}'
```

`follower_id` and `creator_id` in the response are internal IDs. The AI always translates them to names using `wecomcli-contact` before showing you anything.

### create_todo

Creates a new todo item.

```bash
wecom-cli todo create_todo '{"content": "Finish the Q2 planning doc", "remind_time": "2026-06-01 09:00:00"}'
```

To assign the todo to someone, include `follower_list`:

```bash
wecom-cli todo create_todo '{"content": "Finish the Q2 planning doc", "remind_time": "2026-06-01 09:00:00", "follower_list": {"followers": [{"follower_id": "zhangsan", "follower_status": 1}]}}'
```

`follower_id` is a `userid` obtained from `wecomcli-contact`. Never guess or construct IDs manually.

### update_todo

Modifies the content, assignees, status, or reminder time of an existing todo.

```bash
wecom-cli todo update_todo '{"todo_id": "TODO_ID", "content": "Updated content", "remind_time": "2026-07-01 09:00:00"}'
```

`follower_list` is a full overwrite — to add a new assignee you must include all existing ones too. The AI fetches the current assignees via `get_todo_detail` before merging.

### delete_todo

Permanently deletes a todo. This action cannot be undone.

```bash
wecom-cli todo delete_todo '{"todo_id": "TODO_ID"}'
```

<Warning>
  The AI always asks for your confirmation before deleting a todo.
</Warning>

### change_todo_user_status

Changes your personal status on a todo: reject, accept, or mark complete.

```bash
wecom-cli todo change_todo_user_status '{"todo_id": "TODO_ID", "user_status": 2}'
```

| `user_status` value | Meaning |
|---------------------|---------|
| `0` | Rejected |
| `1` | Accepted |
| `2` | Completed |

## Status reference

| Field | Value | Meaning |
|-------|-------|---------|
| `todo_status` | `0` | Completed |
| `todo_status` | `1` | In progress |
| `todo_status` | `2` | Deleted |
| `user_status` / `follower_status` | `0` | Rejected |
| `user_status` / `follower_status` | `1` | Accepted |
| `user_status` / `follower_status` | `2` | Completed |

## Typical workflows

### Viewing your todos

<Steps>
  <Step title="Fetch the todo list">
    ```bash
    wecom-cli todo get_todo_list '{}'
    ```
    Pass time filters if you asked for a specific period (for example, "this month's todos").
  </Step>
  <Step title="Fetch full details">
    ```bash
    wecom-cli todo get_todo_detail '{"todo_id_list": ["TODO_ID_1", "TODO_ID_2"]}'
    ```
    The AI always does this immediately after `get_todo_list`. It never shows you a list of bare IDs.
  </Step>
  <Step title="Translate IDs to names">
    ```bash
    wecom-cli contact get_userlist '{}'
    ```
    The AI maps `creator_id` and each `follower_id` to their display names. Unknown IDs are shown as "Unknown user (ID: xxx)".
  </Step>
  <Step title="Display the results">
    The AI shows each todo's content, assignees, reminder time, and status.
  </Step>
</Steps>

<Tip>
  If `has_more` is `true` in the `get_todo_list` response, the AI explicitly tells you that more todos exist and asks whether you want to load the next page.
</Tip>

### Creating a todo with an assignee

<Steps>
  <Step title="Look up the assignee's userid">
    ```bash
    wecom-cli contact get_userlist '{}'
    ```
    The AI filters the result to find the person you named.
  </Step>
  <Step title="Create the todo">
    ```bash
    wecom-cli todo create_todo '{"content": "Complete the requirements doc", "remind_time": "2026-06-01 09:00:00", "follower_list": {"followers": [{"follower_id": "zhangsan", "follower_status": 1}]}}'
    ```
  </Step>
</Steps>

### Marking a todo complete

There are two scenarios:

**Scenario A — closing the todo for everyone** (you are the creator and want to mark it done):

```bash
wecom-cli todo update_todo '{"todo_id": "TODO_ID", "todo_status": 0}'
```

**Scenario B — recording your own completion** (you are an assignee marking your copy done):

```bash
wecom-cli todo change_todo_user_status '{"todo_id": "TODO_ID", "user_status": 2}'
```

### Updating a todo

<Steps>
  <Step title="Find the todo">
    ```bash
    wecom-cli todo get_todo_list '{}'
    ```
    Then fetch details and match the item by content to get its `todo_id`.
  </Step>
  <Step title="Apply the update">
    ```bash
    wecom-cli todo update_todo '{"todo_id": "TODO_ID", "remind_time": "2026-04-10 09:00:00"}'
    ```
    Only include the fields you want to change.
  </Step>
</Steps>

### Deleting a todo

<Steps>
  <Step title="Find the todo">
    The AI calls `get_todo_list` and `get_todo_detail` to locate the target item by content.
  </Step>
  <Step title="Confirm with you">
    The AI shows you the todo content and asks for explicit confirmation before deleting.
  </Step>
  <Step title="Delete it">
    ```bash
    wecom-cli todo delete_todo '{"todo_id": "TODO_ID"}'
    ```
  </Step>
</Steps>

## Key constraints

- `todo_id` must always come from `get_todo_list`. The AI never constructs or guesses IDs.
- `follower_id` (assignee) must come from `wecomcli-contact`. The AI never guesses IDs from names.
- `get_todo_detail` accepts at most 20 IDs per call. Larger batches are split automatically.
- On HTTP errors, the AI retries up to 3 times before reporting the failure.
- If `errcode` is not `0`, the AI reports the `errmsg` value to you.