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.

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"
# Add to ~/.bashrc or ~/.zshrc to persist

Build from source

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

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

2. Configure redirect URL

In the app's Security Settings, add

http://127.0.0.1

as a redirect URL.

3. Publish the app

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

4. Whitelist (beta)

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

5. Authenticate

bash

# Via CLI flags
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.

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)

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

Contacts

bash

# Search users
dws contact user search --keyword "Alice"

# List departments
dws contact department list

# Get user details
dws contact user get --user-id <userId>

Calendar

bash

# 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>"

# Check room availability
dws calendar room list

Todo

bash

# List tasks
dws todo task list

# Create a task
dws todo task create \
  --title "Prepare quarterly report" \
  --executors "<userId>"

# Complete a task
dws todo task complete --task-id <taskId>

Chat

bash

# List groups
dws chat group list

# Send a message via webhook
dws chat webhook send \
  --url $DINGTALK_WEBHOOK_URL \
  --content "Deployment succeeded ✅"

# Send robot message
dws chat robot send \
  --group-id <groupId> \
  --content "Hello from dws"

Attendance

bash

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

# List shift schedules
dws attendance shift list

Approval

bash

# 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

DING Messages

bash

# Send a DING message
dws ding send --receiver-ids "<userId>" --content "Urgent: please review PR"

# Recall a DING message
dws ding recall --ding-id <dingId>

AI Table (aitable)

bash

# List tables
dws aitable table list --space-id <spaceId>

# Query records
dws aitable record list --table-id <tableId>

Developer Docs

bash

# Search DingTalk open platform docs
dws devdoc search --keyword "webhook"

Workbench

bash

# List workbench apps
dws workbench app list

Output Formats

All commands support

-f

--format

bash

# Human-readable table (default)
dws contact user search --keyword "Alice" -f table

# Structured JSON (for agents and piping)
dws contact user search --keyword "Alice" -f json

# Raw API response
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

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

Shell Completion

bash

# 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

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

Common Patterns

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

bash

#!/bin/bash
set -euo pipefail

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

echo "Found user: $USER_ID"

# Create a todo assigned to that user
dws todo task create \
  --title "Review design doc" \
  --executors "$USER_ID" \
  -f json

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

CI/CD: post build status to a DingTalk group

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"

Using dws in a Go project

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)
    }
}

AI Agent Integration

dws

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

.agents/skills/

Install skills for a specific project

bash

# 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.

Typical agent prompts that trigger dws

"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"

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

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

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

# Get structured error details
dws todo task list -f json
# Response includes: 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

dingtalk-workspace-cli

NPX Install

Tags

SKILL.md Content

DingTalk Workspace CLI (dws)

Installation

One-liner (recommended)

Build from source

Prerequisites & Setup

1. Create a DingTalk app

2. Configure redirect URL

3. Publish the app

4. Whitelist (beta)

5. Authenticate

Environment Variables

Key Commands

Authentication

Contacts

Calendar

Todo

Chat

Attendance

Approval

DING Messages

AI Table (aitable)

Developer Docs

Workbench

Output Formats

Dry Run

Shell Completion

Exit Codes

Common Patterns

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

Scripting: send a daily standup reminder

CI/CD: post build status to a DingTalk group

Using dws in a Go project

AI Agent Integration

Install skills for a specific project

Typical agent prompts that trigger dws

Architecture Overview

Development

Troubleshooting