dingtalk-workspace-cli

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:

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

Windows (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:

export PATH="$HOME/.local/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrc to persist

Build from source

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

# 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

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

Contacts

# 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

# 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

# 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

# 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

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

# List shift schedules
dws attendance shift list

Approval

# 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

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

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

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

Developer Docs

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

Workbench

# List workbench apps
dws workbench app list

---

Output Formats

All commands support -f / --format:

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

dws contact user search --keyword "Alice" -f json -o results.json

---

Dry Run

Preview the MCP tool call without executing it:

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

---

Shell Completion

# 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

#!/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

#!/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

#!/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

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

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

---

Development

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

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:

  rm -rf "${DWS_CONFIG_DIR:-$HOME/.config/dws}/cache"
  

• Set DWS_SERVERS_URL if using a custom registry

API errors (exit code 1)

# Get structured error details
dws todo task list -f json
# Response includes: category, reason, hint, actions

Inspect raw requests

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

Allow HTTP for local dev/testing

export DWS_ALLOW_HTTP_ENDPOINTS=1