DingTalk Workspace CLI (dws)
Website: https://www.dingtalk.com CLI Tool: dws Repository: https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli License: Apache-2.0
Description
Official command-line tool for DingTalk Open Platform, built for humans and AI agents. Covers 12 products with 104 tools including Contact, Chat, Calendar, Todo, Approval, Attendance, Report, AITable (多维表格), and more. Features smart input correction, schema introspection, and built-in Agent Skills for seamless AI integration.
Install
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
Install Agent Skills:
curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh
Setup
# Set credentials
export DWS_CLIENT_ID=<your-app-key>
export DWS_CLIENT_SECRET=<your-app-secret>
# Login
dws auth login
Or with flags:
dws auth login --client-id <your-app-key> --client-secret <your-app-secret>
Commands
| Command | Description |
|---|---|
dws auth login |
OAuth login |
dws contact user search |
Search users |
dws contact user get-self |
Get current user |
dws chat message send-by-bot |
Send bot message |
dws calendar event list |
List calendar events |
dws todo task create |
Create todo |
dws todo task list |
List todos |
dws oa approval |
Approval workflows |
dws attendance record |
Attendance records |
dws report list |
List reports |
dws aitable record query |
Query AITable records |
Key Services
| Service | Description |
|---|---|
| Contact | Search users, departments, profiles |
| Chat | Groups, messages, topic replies |
| Bot | Robot messaging, webhooks |
| Calendar | Events, meeting rooms, free/busy |
| Todo | Tasks CRUD |
| Approval (OA) | Approve/reject workflows |
| Attendance | Clock-in records, shifts |
| Report | Create/list reports |
| AITable | Tables, records, fields (多维表格) |
| Ding | Send DING messages |
Examples
Search Contacts
dws contact user search --keyword "engineering"
Calendar
# List events
dws calendar event list
# Preview without executing
dws todo task list --dry-run
Create Todo
dws todo task create --title "Quarterly report" --executors "<user-id>" --yes
Send Bot Message
dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
--title "Report" --text "Hello team"
# Read from file
dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
--title "Weekly" --text @report.md
AITable (多维表格)
# Query records
dws aitable record query --base-id BASE_ID --table-id TABLE_ID --limit 10
# With jq filter
dws aitable record query --base-id BASE_ID --table-id TABLE_ID --jq '.invocation.params'
Schema Discovery
# List all products
dws schema --jq '.products[] | {id, tool_count: (.tools | length)}'
# View tool parameters
dws schema aitable.query_records --jq '.tool.parameters'
AI Agent Integration
dws is AI-native. Works with Claude Code, Cursor, and other AI agents.
# Set credentials for agents (no interactive login)
export DWS_CLIENT_ID=<your-app-key>
export DWS_CLIENT_SECRET=<your-app-secret>
dws auth login
# Use --yes to skip confirmations (required for agents)
dws todo task create --title "Review PR" --executors "<user-id>" --yes
# Use --dry-run for safe preview
dws contact user search --keyword "test" --dry-run
# Use --jq to extract data (save tokens)
dws contact user get-self --jq '.result[0].orgEmployeeModel | {name, dept}'
Smart Features
| Feature | Description |
|---|---|
| Auto-correction | Fixes common AI mistakes (camelCase → kebab-case) |
| jq filtering | --jq for precise extraction |
| Schema introspection | dws schema to discover APIs |
| Dry-run | --dry-run to preview calls |
| File input | --text @file.md reads from file |
Notes
- Whitelist required: Currently in co-creation phase, requires admin authorization
- Credentials: Stored encrypted in OS Keychain (PBKDF2 + AES-256-GCM)
- Security: All API calls go through DingTalk Open Platform with full audit
- 104 tools across 12 products
Comments (0)
Add a Comment
No comments yet. Be the first to comment!