Interact with DingTalk enterprise workspace using the dws CLI. Required: dws CLI, DWS_CLIENT_ID, DWS_CLIENT_SECRET. Use for: contacts, chat, calendar, todo, approvals, attendance, reports, AITable.
Use the dws CLI to interact with DingTalk enterprise workspace. This skill covers all 12 products: contact, chat, bot, calendar, todo, oa (approval), attendance, ding, report, aitable, workbench, and devdoc.
⚠️ Security & Safety Notes
Read before installing:
1. Credentials Required: This skill requires OAuth credentials (DWSCLIENTID, DWSCLIENTSECRET) from a DingTalk Open Platform app. Enterprise admin approval may be needed.
2. Install Safely: The dws CLI installer fetches from GitHub. Review the installer script before running:
3. Autonomous Execution Risk: This skill can perform destructive actions (approve workflows, send messages, delete records). Always use --dry-run first and restrict autonomous invocation unless you trust the agent.
4. Least Privilege: Use scoped OAuth credentials with minimum permissions. Test in a sandbox enterprise first.
Prerequisites
Installation
Option 1: Install from release (recommended)
Download pre-built binary from https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases
Before making calls, discover available capabilities:
CODEBLOCK5
Quick Reference by Product
Contact
CODEBLOCK6
Chat
CODEBLOCK7
Calendar
CODEBLOCK8
Todo
CODEBLOCK9
Approval (OA)
CODEBLOCK10
Attendance
CODEBLOCK11
Report
CODEBLOCK12
AITable
CODEBLOCK13
Output Control
jq Filtering
CODEBLOCK14
Field Selection
CODEBLOCK15
File Input
CODEBLOCK16
Common Workflows
See bundled scripts in scripts/ for batch operations:
Safety First: All mutation scripts default to --dry-run mode. You must explicitly pass --execute to perform actual changes.
Script
Description
INLINECODE21
Create event + add participants + book meeting room (use --execute to book)
INLINECODE23
Find common free slots across multiple people (read-only) |
| todo_batch_create.py | Batch create todos from JSON (use --execute to create) |
| contact_dept_members.py | Search department and list all members (read-only) |
| report_inbox_today.py | View today's received reports (read-only) |
| import_records.py | Import CSV records into AITable (use --execute to import) |
Example:
CODEBLOCK17
Error Handling
Common Error Codes
- INVALID_TOKEN: Re-authenticate with INLINECODE31
INLINECODE32 : Check app permissions in DingTalk Open Platform
INLINECODE33 : Verify IDs with dws schema introspection
Recovery
When encountering RECOVERY_EVENT_ID, use:
CODEBLOCK18
Security Notes
- Credentials are stored encrypted in system Keychain (never in config files)
All requests use HTTPS to *.dingtalk.com only
Use --dry-run before any mutation to preview the API call
Token refresh is automatic; no manual intervention needed
Reference Files
- Product commands: See references/products/*.md for detailed command reference per product
Intent guide: See references/intent-guide.md for disambiguation (e.g., report vs todo)
Error codes: See references/error-codes.md for debugging workflows
Global reference: See references/global-reference.md for auth, output formats, global flags
- Add support for mapping CSV column names to AITable field names in import_records.py using a new --field-map argument.
- Update documentation in SKILL.md to reflect the new --field-map option for importing records.
- Improves bulk data migration workflows with flexible column/field alignment.