DingTalk Workspace CLI (dws)

dws — DingTalk Workspace on the command line, built for humans and AI agents.

中文版 · English · Reference · Changelog

[!IMPORTANT] Co-creation Phase: This project accesses DingTalk enterprise data and requires enterprise admin authorization. Please join the DingTalk DWS co-creation group to complete whitelist configuration. See Getting Started below.

Why dws?

• For humans — --help for usage, --dry-run to preview requests, -f table/json/raw for output formats.
• For AI agents — structured JSON responses + built-in Agent Skills, ready out of the box.
• For enterprise admins — zero-trust architecture: OAuth device-flow auth + domain allowlisting + least-privilege scoping. Not a single byte can bypass authentication and audit.

Installation

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

git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
cd dingtalk-workspace-cli
go build -o dws ./cmd       # build to current directory
cp dws ~/.local/bin/         # install to PATH

Getting Started

Step 1: Create a DingTalk Application

Go to the Open Platform Console. Under "Internal Enterprise Apps - DingTalk Apps", click Create App.

Step 2: Configure Redirect URL

Go to app settings → Security Settings. Add the following redirect URLs and save:

http://127.0.0.1
https://login.dingtalk.com

http://127.0.0.1 is for local browser login; https://login.dingtalk.com is for --device device-flow login (Docker containers, remote servers, and other headless environments). We recommend configuring both.

Step 3: Publish the Application

Click "App Release - Version Management & Release" to publish and go live.

Step 4: Request Whitelist Access

Join the DingTalk DWS co-creation group and provide your Client ID and admin confirmation to complete whitelist setup.

Step 5: Authenticate

dws auth login --client-id <your-app-key> --client-secret <your-app-secret>

Or via environment variables:

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

CLI flags take precedence over environment variables. Credentials are used for DingTalk's OAuth device flow.

Quick Start

dws contact user search --keyword "engineering"     # search contacts
dws calendar event list                            # list calendar events
dws todo task create --title "Quarterly report" --executors "<your-userId>"   # create a todo (replace <your-userId>)
dws todo task list --dry-run                       # preview without executing

Using with Agents

dws is designed as an AI-native CLI. Complete Installation and Getting Started first, then configure your agent:

# Configure auth via environment variables (recommended for agents, no interactive login)
export DWS_CLIENT_ID=<your-app-key>
export DWS_CLIENT_SECRET=<your-app-secret>
dws auth login

Agent Invocation Patterns

# Use --yes to skip confirmation prompts (required for agents)
dws todo task create --title "Review PR" --executors "<your-userId>" --yes

# Use --dry-run to preview operations (safe execution)
dws contact user search --keyword "engineering" --dry-run

# Use --jq to extract precisely (save tokens)
dws contact user get-self --jq '.result[0].orgEmployeeModel | {name: .orgUserName, dept: .depts[0].deptName, userId}'

Schema Discovery

Agents don't need pre-built knowledge of every command. Use dws schema to dynamically discover capabilities:

# Step 1: Discover all available products
dws schema --jq '.products[] | {id, tool_count: (.tools | length)}'

# Step 2: Inspect target tool's parameter schema
dws schema aitable.query_records --jq '.tool.input_schema'

# Step 3: Construct the correct call
dws aitable record query --base-id BASE_ID --table-id TABLE_ID --limit 10

Agent Skills

The repo ships Agent Skills (SKILL.md files) for every DingTalk product. After installing, tools like Claude Code / Cursor can use DingTalk capabilities directly:

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

install.sh installs to $HOME/.agents/skills/dws (global); install-skills.sh installs to ./.agents/skills/dws (current project).

Author your own Agent Skills and orchestrate them with dws skills for cross-product workflows: ISV Skill → dws Skill → DingTalk Open Platform API (enforced auth + full audit).

Features

# Naming convention auto-conversion (camelCase / snake_case / UPPER -> kebab-case)
dws aitable record query --baseId BASE_ID --tableId TABLE_ID         # auto-corrected to --base-id --table-id

# Sticky argument splitting
dws contact user search --keyword "engineering" --timeout30           # auto-split to --timeout 30

# Fuzzy flag name matching
dws aitable record query --base-id BASE_ID --tabel-id TABLE_ID       # --tabel-id -> --table-id

# Value normalization (boolean / number / date / enum)
# "yes" -> true, "1,000" -> 1000, "2024/03/29" -> "2024-03-29", "ACTIVE" -> "active"

# Built-in jq expressions
dws aitable record query --base-id BASE_ID --table-id TABLE_ID --jq '.invocation.params'
dws schema --jq '.products[] | {id, tools: (.tools | length)}'

# Return only specific fields
dws aitable record query --base-id BASE_ID --table-id TABLE_ID --fields invocation,response

dws schema                                              # list all products and tools
dws schema aitable.query_records                        # view parameter schema
dws schema aitable.query_records --jq '.tool.input_schema.required'   # view required fields
dws schema --jq '.products[].id'                        # extract all product IDs

# Read message body from a file
dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
  --title "Weekly Report" --text @report.md

# Pipe content via stdin
cat report.md | dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
  --title "Weekly Report"

# Read from stdin explicitly
dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
  --title "Weekly Report" --text @-

Key Services

Run dws --help for the full list, or dws <service> --help for subcommands.

Security by Design

dws treats security as a first-class architectural concern, not an afterthought. Credentials never touch disk, tokens never leave trusted domains, permissions never exceed grants, operations never escape audit — every API call must pass through DingTalk Open Platform's authentication and audit chain, no exceptions.

Found a vulnerability? Report via GitHub Security Advisories. See SECURITY.md.

Reference & Docs

• Reference — environment variables, exit codes, output formats, shell completion
• Architecture — discovery-driven pipeline, IR, transport layer
• Changelog — release history and migration notes

Contributing

See CONTRIBUTING.md for build instructions, testing, and development workflow.

License

Apache-2.0