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.

Table of Contents

• Why dws?
• Installation
• Getting Started
• Quick Start
• Key Services
• Security by Design
• AI Agent Skills
• Reference & Docs
• Contributing

---

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

Other install methods

Pre-built binary: download from GitHub Releases.

Build from source:

git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
cd dingtalk-workspace-cli
make build

The binary installs to ~/.local/bin by default. If dws is not found, add it to PATH: export PATH="$HOME/.local/bin:$PATH"

Getting Started

Step 1: Create a DingTalk Application

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

View screenshot

Step 2: Configure Redirect URL

Go to app settings → Security Settings. Enter http://127.0.0.1 as the redirect URL and save.

View screenshot

Step 3: Publish the Application

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

View screenshot

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 "Alice"          # search contacts
dws calendar event list                            # list calendar events
dws todo task create --title "Quarterly report" --executors "<userId>"   # create a todo
dws todo task list --dry-run                       # preview without executing

Key Services

Service	Command	Description
Contact	contact	Users / departments
Chat	chat	Group management / members / bot messaging / webhook
Calendar	calendar	Events / meeting rooms / free-busy
Todo	todo	Task management
Approval	approval	Processes / forms / instances
Attendance	attendance	Clock-in / shifts / statistics
Ding	ding	DING messages / send / recall
Report	report	Reports / templates / statistics
AITable	aitable	AI table operations
Workbench	workbench	App query
DevDoc	devdoc	Open platform docs search

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

Coming soon

doc (documents) · mail (email) · minutes (AI transcription) · drive (cloud drive) · conference (video) · tb (Teambition) · aiapp (AI apps) · live (streaming) · skill (marketplace)

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.

For Developers

Mechanism	Details
Encrypted token storage	PBKDF2 (600,000 iterations) + AES-256-GCM, keyed by device MAC address — tokens cannot be decrypted on another machine
Domain allowlist	DWS_TRUSTED_DOMAINS defaults to *.dingtalk.com; bearer tokens are never sent to non-allowlisted domains
HTTPS enforced	All requests require TLS; HTTP only permitted for loopback during development
Dry-run preview	--dry-run shows call parameters without executing, preventing accidental mutations
Zero credential persistence	Client ID / Secret used in memory only — never written to config files or logs

For Enterprise Admins

Mechanism	Details
OAuth device-flow auth	Users must authenticate through an admin-authorized DingTalk application
Least-privilege scoping	CLI can only invoke APIs granted to the application — no privilege escalation
Allowlist gating	Admin confirmation required during co-creation phase; self-service approval planned
Full-chain audit	Every data read/write passes through the DingTalk Open Platform API — enterprise admins can trace complete call logs in real time; no anomalous operation can hide

For ISVs

Mechanism	Details
Tenant data isolation	Operates under authorized app identity; cross-tenant access is impossible
Skill sandbox	Agent Skills are Markdown documents (SKILL.md) — prompt descriptions only, no arbitrary code execution
Zero blind spots	Every API call during ISV–dws skill orchestration is forced through DingTalk Open Platform authentication — full call chain is traceable with no bypass path

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

AI Agent Skills

The repo ships Agent Skills (SKILL.md files) for every DingTalk product. The install script deploys them to ~/.agents/skills/dws automatically.

# Install skills into the current project only
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).

ISV Skill Integration

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

Example: A CRM Skill invokes the Calendar Skill to create a client meeting, then triggers the Todo Skill to assign follow-ups — the AI agent completes cross-system collaboration in a single conversation.

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