dingtalk-workspace-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DingTalk Workspace CLI (dws)

Skill by ara.so — Daily 2026 Skills collection.

dws

is an officially open-sourced cross-platform CLI tool from DingTalk that unifies DingTalk's full product suite into a single binary. It is designed for both human users and AI agent workflows. Every response is structured JSON, and built-in Agent Skills let LLMs use DingTalk out of the box.

由ara.so提供的Skill — 2026每日技能合集。

dws

是钉钉官方开源的跨平台CLI工具，将钉钉全产品套件整合为单个二进制文件。它同时面向人类用户和AI Agent工作流设计，所有响应均为结构化JSON格式，内置的Agent Skills让大语言模型可直接开箱即用钉钉功能。

Installation

安装

One-liner (recommended)

一键安装（推荐）

macOS / Linux:

bash

curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh

Windows (PowerShell):

powershell

irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.ps1 | iex

The installer:

Auto-detects OS and architecture
Downloads a pre-compiled binary to
```
~/.local/bin
```
Installs Agent Skills to
```
~/.agents/skills/dws
```

Add to PATH if needed:

bash

export PATH="$HOME/.local/bin:$PATH"

macOS / Linux：

bash

curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh

Windows（PowerShell）：

powershell

irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.ps1 | iex

安装程序会：

自动检测操作系统和架构
将预编译二进制文件下载至
```
~/.local/bin
```
将Agent Skills安装至
```
~/.agents/skills/dws
```

如需添加至PATH：

bash

export PATH="$HOME/.local/bin:$PATH"

Add to ~/.bashrc or ~/.zshrc to persist

添加至~/.bashrc或~/.zshrc以持久生效

undefined

undefined

Build from source

从源码构建

bash

git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
cd dingtalk-workspace-cli
make build
./dws version

bash

git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
cd dingtalk-workspace-cli
make build
./dws version

Prerequisites & Setup

前提条件与配置

1. Create a DingTalk app

1. 创建钉钉应用

Go to DingTalk Open Platform, create an enterprise internal app, and note the Client ID (AppKey) and Client Secret (AppSecret).

访问钉钉开放平台，创建企业内部应用，并记录Client ID（AppKey）和Client Secret（AppSecret）。

2. Configure redirect URL

2. 配置重定向URL

In the app's Security Settings, add

http://127.0.0.1

as a redirect URL.

在应用的安全设置中，添加

http://127.0.0.1

作为重定向URL。

3. Publish the app

3. 发布应用

Go to App Release → Version Management and publish the app so it is active.

进入应用发布 → 版本管理，发布应用使其处于激活状态。

4. Whitelist (beta)

4. 白名单（测试版）

During the co-creation phase, join the DingTalk DWS group and provide your Client ID and enterprise admin confirmation to be whitelisted.

在共创阶段，加入钉钉DWS群组，提供你的Client ID和企业管理员确认信息以加入白名单。

5. Authenticate

5. 身份验证

bash

undefined

bash

undefined

Via CLI flags

通过CLI参数

dws auth login --client-id $DWS_CLIENT_ID --client-secret $DWS_CLIENT_SECRET

Or set env vars first, then login

或先设置环境变量再登录

export DWS_CLIENT_ID=your-app-key export DWS_CLIENT_SECRET=your-app-secret dws auth login


Tokens are stored encrypted with **PBKDF2 (600,000 iterations) + AES-256-GCM**, keyed to your device MAC address.

---

export DWS_CLIENT_ID=your-app-key export DWS_CLIENT_SECRET=your-app-secret dws auth login


令牌通过**PBKDF2（600,000次迭代）+ AES-256-GCM**加密存储，密钥与设备MAC地址绑定。

---

Environment Variables

环境变量

Variable	Purpose
`DWS_CLIENT_ID`	OAuth Client ID (DingTalk AppKey)
`DWS_CLIENT_SECRET`	OAuth Client Secret (DingTalk AppSecret)
`DWS_CONFIG_DIR`	Override default config directory
`DWS_SERVERS_URL`	Custom server registry endpoint
`DWS_TRUSTED_DOMAINS`	Comma-separated domains for bearer token (default: `*.dingtalk.com` )
`DWS_ALLOW_HTTP_ENDPOINTS`	Set to `1` to allow HTTP on loopback (dev only)

变量名称	用途
`DWS_CLIENT_ID`	OAuth Client ID（钉钉AppKey）
`DWS_CLIENT_SECRET`	OAuth Client Secret（钉钉AppSecret）
`DWS_CONFIG_DIR`	覆盖默认配置目录
`DWS_SERVERS_URL`	自定义服务注册端点
`DWS_TRUSTED_DOMAINS`	承载令牌的可信域名列表（逗号分隔，默认： `*.dingtalk.com` ）
`DWS_ALLOW_HTTP_ENDPOINTS`	设置为 `1` 以允许环回接口使用HTTP（仅开发环境）

Key Commands

核心命令

Authentication

身份验证

bash

dws auth login                        # Authenticate via OAuth device flow
dws auth logout                       # Remove stored credentials
dws auth status                       # Show current auth status

bash

dws auth login                        # 通过OAuth设备流进行身份验证
dws auth logout                       # 删除存储的凭证
dws auth status                       # 显示当前身份验证状态

Contacts

联系人

bash

undefined

bash

undefined

Search users

搜索用户

dws contact user search --keyword "Alice"

List departments

列出部门

dws contact department list

Get user details

获取用户详情

dws contact user get --user-id <userId>

undefined

dws contact user get --user-id <userId>

undefined

Calendar

日历

bash

undefined

bash

undefined

List events

列出事件

dws calendar event list

Create an event

创建事件

dws calendar event create
--title "Q2 Planning"
--start "2026-04-01T10:00:00+08:00"
--end "2026-04-01T11:00:00+08:00"
--attendees "<userId1>,<userId2>"

dws calendar event create
--title "Q2规划会议"
--start "2026-04-01T10:00:00+08:00"
--end "2026-04-01T11:00:00+08:00"
--attendees "<userId1>,<userId2>"

Check room availability

检查会议室可用性

dws calendar room list

undefined

dws calendar room list

undefined

Todo

待办事项

bash

undefined

bash

undefined

List tasks

列出任务

dws todo task list

Create a task

创建任务

dws todo task create
--title "Prepare quarterly report"
--executors "<userId>"

dws todo task create
--title "准备季度报告"
--executors "<userId>"

Complete a task

完成任务

dws todo task complete --task-id <taskId>

undefined

dws todo task complete --task-id <taskId>

undefined

Chat

聊天

bash

undefined

bash

undefined

List groups

列出群组

dws chat group list

Send a message via webhook

通过Webhook发送消息

dws chat webhook send
--url $DINGTALK_WEBHOOK_URL
--content "Deployment succeeded ✅"

dws chat webhook send
--url $DINGTALK_WEBHOOK_URL
--content "部署成功 ✅"

Send robot message

发送机器人消息

dws chat robot send
--group-id <groupId>
--content "Hello from dws"

undefined

dws chat robot send
--group-id <groupId>
--content "来自dws的问候"

undefined

Attendance

考勤

bash

undefined

bash

undefined

Get attendance records

获取考勤记录

dws attendance record list --user-id <userId> --date "2026-03-01"

List shift schedules

列出排班表

dws attendance shift list

undefined

dws attendance shift list

undefined

Approval

审批

bash

undefined

bash

undefined

List approval templates

列出审批模板

dws approval template list

Submit an approval instance

提交审批实例

dws approval instance create
--process-code <processCode>
--form-values '{"key":"value"}'

Query approval instances

查询审批实例

dws approval instance list --status RUNNING

undefined

dws approval instance list --status RUNNING

undefined

DING Messages

DING消息

bash

undefined

bash

undefined

Send a DING message

发送DING消息

dws ding send --receiver-ids "<userId>" --content "Urgent: please review PR"

dws ding send --receiver-ids "<userId>" --content "紧急：请查看PR"

Recall a DING message

撤回DING消息

dws ding recall --ding-id <dingId>

undefined

dws ding recall --ding-id <dingId>

undefined

AI Table (aitable)

AI表格（aitable）

bash

undefined

bash

undefined

List tables

列出表格

dws aitable table list --space-id <spaceId>

Query records

查询记录

dws aitable record list --table-id <tableId>

undefined

dws aitable record list --table-id <tableId>

undefined

Developer Docs

开发者文档

bash

undefined

bash

undefined

Search DingTalk open platform docs

搜索钉钉开放平台文档

dws devdoc search --keyword "webhook"

undefined

dws devdoc search --keyword "webhook"

undefined

Workbench

工作台

bash

undefined

bash

undefined

List workbench apps

列出工作台应用

dws workbench app list

---

dws workbench app list

---

Output Formats

输出格式

All commands support

-f

--format

bash

undefined

所有命令均支持

-f

--format

参数：

bash

undefined

Human-readable table (default)

人类可读表格（默认）

dws contact user search --keyword "Alice" -f table

Structured JSON (for agents and piping)

结构化JSON（适用于Agent和管道操作）

dws contact user search --keyword "Alice" -f json

Raw API response

原始API响应

dws contact user search --keyword "Alice" -f raw


Save output to a file:
```bash
dws contact user search --keyword "Alice" -f json -o results.json

dws contact user search --keyword "Alice" -f raw


将输出保存至文件：
```bash
dws contact user search --keyword "Alice" -f json -o results.json

Dry Run

试运行

Preview the MCP tool call without executing it:

bash

dws todo task list --dry-run
dws calendar event create --title "Test" --dry-run

预览MCP工具调用而不实际执行：

bash

dws todo task list --dry-run
dws calendar event create --title "测试" --dry-run

Shell Completion

Shell自动补全

bash

undefined

bash

undefined

Bash

dws completion bash > /etc/bash_completion.d/dws

Zsh

dws completion zsh > "${fpath[1]}/_dws"

Fish

dws completion fish > ~/.config/fish/completions/dws.fish

---

dws completion fish > ~/.config/fish/completions/dws.fish

---

Exit Codes

退出码

Code	Category	Meaning
0	Success	Command completed successfully
1	API	MCP tool call or upstream API failure
2	Auth	Authentication or authorization failure
3	Validation	Bad input flags or schema mismatch
4	Discovery	Service discovery or cache failure
5	Internal	Unexpected internal error

When using

-f json

, errors include structured fields:

category

reason

hint

actions

代码	分类	含义
0	成功	命令执行完成
1	API	MCP工具调用或上游API失败
2	身份验证	身份验证或授权失败
3	验证	输入参数错误或 schema 不匹配
4	发现	服务发现或缓存失败
5	内部	意外内部错误

使用

-f json

时，错误信息包含结构化字段：

category

、

reason

、

hint

、

actions

。

Common Patterns

常见使用场景

Scripting: find a user then create a todo assigned to them

脚本：查找用户并创建分配给该用户的待办事项

bash

#!/bin/bash
set -euo pipefail

bash

#!/bin/bash
set -euo pipefail

Search for user and extract userId

搜索用户并提取userId

USER_ID=$(dws contact user search --keyword "Alice" -f json |
jq -r '.data[0].userId')

echo "Found user: $USER_ID"

USER_ID=$(dws contact user search --keyword "Alice" -f json |
jq -r '.data[0].userId')

echo "找到用户：$USER_ID"

Create a todo assigned to that user

创建分配给该用户的待办事项

dws todo task create
--title "Review design doc"
--executors "$USER_ID"
-f json

undefined

dws todo task create
--title "评审设计文档"
--executors "$USER_ID"
-f json

undefined

Scripting: send a daily standup reminder

脚本：发送每日站会提醒

bash

#!/bin/bash
dws ding send \
  --receiver-ids "$TEAM_USER_IDS" \
  --content "🕘 Daily standup in 5 minutes — please join!" \
  -f json

bash

#!/bin/bash
dws ding send \
  --receiver-ids "$TEAM_USER_IDS" \
  --content "🕘 5分钟后召开每日站会 — 请准时参加！" \
  -f json

CI/CD: post build status to a DingTalk group

CI/CD：将构建状态发布到钉钉群组

bash

#!/bin/bash
STATUS=${1:-"unknown"}
EMOJI=$([[ "$STATUS" == "success" ]] && echo "✅" || echo "❌")

dws chat webhook send \
  --url "$DINGTALK_WEBHOOK_URL" \
  --content "$EMOJI Build #$BUILD_NUMBER $STATUS — $BUILD_URL"

bash

#!/bin/bash
STATUS=${1:-"unknown"}
EMOJI=$([[ "$STATUS" == "success" ]] && echo "✅" || echo "❌")

dws chat webhook send \
  --url "$DINGTALK_WEBHOOK_URL" \
  --content "$EMOJI 构建 #$BUILD_NUMBER $STATUS — $BUILD_URL"

Using dws in a Go project

在Go项目中使用dws

package main

import (
    "os/exec"
    "encoding/json"
    "fmt"
)

type SearchResult struct {
    Data []struct {
        UserID string `json:"userId"`
        Name   string `json:"name"`
    } `json:"data"`
}

func searchDingTalkUser(keyword string) (*SearchResult, error) {
    cmd := exec.Command("dws", "contact", "user", "search",
        "--keyword", keyword,
        "-f", "json",
    )
    out, err := cmd.Output()
    if err != nil {
        return nil, fmt.Errorf("dws error: %w", err)
    }
    var result SearchResult
    if err := json.Unmarshal(out, &result); err != nil {
        return nil, err
    }
    return &result, nil
}

func main() {
    result, err := searchDingTalkUser("Alice")
    if err != nil {
        panic(err)
    }
    for _, u := range result.Data {
        fmt.Printf("User: %s (%s)\n", u.Name, u.UserID)
    }
}

package main

import (
    "os/exec"
    "encoding/json"
    "fmt"
)

type SearchResult struct {
    Data []struct {
        UserID string `json:"userId"`
        Name   string `json:"name"`
    } `json:"data"`
}

func searchDingTalkUser(keyword string) (*SearchResult, error) {
    cmd := exec.Command("dws", "contact", "user", "search",
        "--keyword", keyword,
        "-f", "json",
    )
    out, err := cmd.Output()
    if err != nil {
        return nil, fmt.Errorf("dws错误：%w", err)
    }
    var result SearchResult
    if err := json.Unmarshal(out, &result); err != nil {
        return nil, err
    }
    return &result, nil
}

func main() {
    result, err := searchDingTalkUser("Alice")
    if err != nil {
        panic(err)
    }
    for _, u := range result.Data {
        fmt.Printf("用户：%s (%s)\n", u.Name, u.UserID)
    }
}

AI Agent Integration

AI Agent集成

dws

installs Agent Skills automatically. Most AI coding agents (Claude Code, Cursor, Windsurf, etc.) auto-discover skills in

.agents/skills/

dws

会自动安装Agent Skills。大多数AI编码Agent（Claude Code、Cursor、Windsurf等）会自动发现

.agents/skills/

目录下的技能。

Install skills for a specific project

为特定项目安装技能

bash

undefined

bash

undefined

Install to current working directory (project-scoped)

安装至当前工作目录（项目级）

curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh


Skills are placed at `./.agents/skills/dws/` — commit these to your repo so all collaborators and agents get DingTalk capabilities automatically.

curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh


技能将被放置在`./.agents/skills/dws/` — 将其提交至代码仓库，以便所有协作者和Agent自动获得钉钉功能。

Typical agent prompts that trigger dws

触发dws的典型Agent提示词

"Find the user ID for Alice in DingTalk"
"Create a todo assigned to Bob for reviewing the PR"
"List my calendar events for tomorrow"
"Send a DING message to the team leads"
"Check attendance records for user X this month"

"在钉钉中查找Alice的用户ID"
"创建一个分配给Bob的待办事项，用于评审PR"
"列出我明天的日历事件"
"给团队负责人发送一条DING消息"
"查看用户X本月的考勤记录"

Architecture Overview

架构概述

dws

uses a discovery-driven pipeline — no product commands are hardcoded:

Market Registry → Discovery → IR (normalized catalog) → CLI (Cobra) → Transport (MCP JSON-RPC)
       ↓               ↓
  mcp.dingtalk.com   Disk cache (TTL + stale-fallback for offline use)

Market — fetches MCP service registry from
```
mcp.dingtalk.com
```
Discovery — resolves service capabilities, cached to disk with TTL and stale fallback
IR — normalizes services into a unified product/tool catalog
CLI — mounts catalog onto a Cobra command tree, maps flags to MCP input params
Transport — executes MCP JSON-RPC calls with retry, auth injection, and response size limits

dws

采用发现驱动管道 — 所有产品命令均未硬编码：

市场注册表 → 发现 → IR（标准化目录）→ CLI（Cobra）→ 传输层（MCP JSON-RPC）
       ↓               ↓
  mcp.dingtalk.com   磁盘缓存（TTL + 离线使用时的过期回退）

市场 — 从
```
mcp.dingtalk.com
```
获取MCP服务注册表
发现 — 解析服务能力，缓存至磁盘并设置TTL和过期回退
IR — 将服务标准化为统一的产品/工具目录
CLI — 将目录挂载到Cobra命令树，将参数映射为MCP输入参数
传输层 — 执行MCP JSON-RPC调用，包含重试、身份验证注入和响应大小限制

Development

开发

bash

make build                       # Build binary
make test                        # Run unit tests
make lint                        # Format + lint
make package                     # Build all release artifacts locally (goreleaser snapshot)
make release                     # Build and release via goreleaser

bash

make build                       # 构建二进制文件
make test                        # 运行单元测试
make lint                        # 格式化 + 代码检查
make package                     # 本地构建所有发布产物（goreleaser快照）
make release                     # 通过goreleaser构建并发布

Troubleshooting

故障排除

dws: command not found

bash

export PATH="$HOME/.local/bin:$PATH"

Auth errors (exit code 2)

Verify
```
DWS_CLIENT_ID
```
and
```
DWS_CLIENT_SECRET
```
are correct
Confirm the app is published and the redirect URL
```
http://127.0.0.1
```
is configured
Confirm your enterprise is whitelisted (required during beta)

Discovery failures (exit code 4)

```
dws
```
caches service discovery; if the cache is stale, delete it:
bash
```
rm -rf "${DWS_CONFIG_DIR:-$HOME/.config/dws}/cache"
```
Set
```
DWS_SERVERS_URL
```
if using a custom registry

API errors (exit code 1)

bash

undefined

dws: command not found

bash

export PATH="$HOME/.local/bin:$PATH"

身份验证错误（退出码2）

验证
```
DWS_CLIENT_ID
```
和
```
DWS_CLIENT_SECRET
```
是否正确
确认应用已发布且重定向URL
```
http://127.0.0.1
```
已配置
确认你的企业已加入白名单（测试版要求）

发现失败（退出码4）

```
dws
```
会缓存服务发现信息；若缓存过期，可删除：
bash
```
rm -rf "${DWS_CONFIG_DIR:-$HOME/.config/dws}/cache"
```
若使用自定义注册表，设置
```
DWS_SERVERS_URL
```

API错误（退出码1）

bash

undefined

Get structured error details

获取结构化错误详情

dws todo task list -f json

Response includes: category, reason, hint, actions

响应包含：category, reason, hint, actions


**Inspect raw requests**
```bash
dws contact user search --keyword "Alice" -f raw

Allow HTTP for local dev/testing

bash

export DWS_ALLOW_HTTP_ENDPOINTS=1


**检查原始请求**
```bash
dws contact user search --keyword "Alice" -f raw

允许本地开发/测试使用HTTP

bash

export DWS_ALLOW_HTTP_ENDPOINTS=1