dingtalk-workspace-cli

[!IMPORTANT] Co-creation Phase: This project accesses DingTalk enterprise data and requires enterprise admin authorization. Join the DingTalk DWS co-creation group for support and updates. See Getting Started below.

• Why dws?
• Installation
• Upgrade
• Getting Started
• Quick Start
• Using with Agents
• Features
• Key Services
• Security by Design
• Reference & Docs
• Contributing

---

• 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

The installer ships skills in one of two layouts. CLI commands (dws aitable ..., dws calendar ...) are identical in both modes — only the agent-side skill layout differs.

🧪 multi is currently EXPERIMENTAL / preview. 22 product-scoped skills all pass the dispatch verifier, but interface, naming and cross-skill references may change in future releases. For production / shared environments, prefer mono. File issues if you hit problems.

How to pick:

• Quick install (one-liner above): non-interactive, installs mono.
• TTY install (download then run): curl -O .../install.sh && bash install.sh — prompts 1) mono 2) multi (default 1).
• Override via env: DWS_SKILL_MODE=multi curl -fsSL ... | sh.
• Switch later: dws skill setup --mode multi (or --mode mono) — re-run any time.

npm (requires Node.js (npm/npx)):

npm install -g dingtalk-workspace-cli

Pre-built binary: download from GitHub Releases.

macOS users: If you see "cannot be opened because Apple cannot check it for malicious software", run:

xattr -d com.apple.quarantine /path/to/dws

Build from source:

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

Static endpoint data is generated from the Wukong baseline and committed in this repository under internal/syncdata, so source builds do not require a sibling data checkout.

Requires Go 1.25+. Use make package to cross-compile for all platforms (macOS / Linux / Windows x amd64 / arm64).

China mirror

For users in mainland China, the following channels avoid GitHub network issues. By default (without setting these environment variables) the installer pulls from GitHub.

1. Install script + pre-built binary (Gitee mirror):

Repository mirror: https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli

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

With DWS_GITEE_REPO set, the installer resolves the latest version and every release asset (binary, checksums, skills) from the Gitee API instead of GitHub. If it is unset, installation defaults to GitHub.

2. npm package (npmmirror mirror):

npm install -g dingtalk-workspace-cli --registry=https://registry.npmmirror.com

npmmirror automatically syncs public packages from the public npm registry, so this works directly in China.

3. Skills only (Gitee mirror):

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

With DWS_GITEE_REPO set, install-skills.sh resolves the version and skills package from Gitee; it also auto-falls back to the Gitee mirror when GitHub is unreachable.

Upgrade

Requires v1.0.7 or later. For earlier versions, please re-run the install script to upgrade.

dws has built-in self-upgrade capability. Updates are pulled directly from GitHub Releases with SHA256 integrity verification and automatic backup.

dws upgrade                    # interactive upgrade to latest version
dws upgrade --check            # check for new versions without installing
dws upgrade --list             # list stable release versions
dws upgrade --beta             # upgrade to the latest beta pre-release
dws upgrade --check --beta     # check the beta track without installing
dws upgrade --list --beta      # list beta pre-release versions
dws upgrade --version v1.0.7   # upgrade to a specific version
dws upgrade --version v1.0.8-beta.1  # upgrade to a specific beta version
dws upgrade --rollback         # rollback to the previous version
dws upgrade -y                 # skip confirmation prompt

By default, dws upgrade follows the stable release track. Use --beta only when you explicitly want the newest GitHub pre-release build.

The upgrade process follows a two-phase atomic flow to ensure consistency:

1. Prepare — downloads the platform-specific binary and skill packages to a temporary directory, verifies SHA256 checksums, and extracts/validates all files. If any step fails, the upgrade aborts without modifying the existing installation.
2. Apply — only after all preparations succeed, the binary is replaced and skill packages are installed to all detected agent directories (~/.agents/skills/dws, ~/.claude/skills/dws, ~/.cursor/skills/dws, etc.).

A backup of the current version is automatically created before each upgrade. Use dws upgrade --rollback to restore the previous version if needed.

Getting Started

dws auth login            # browser opens automatically
dws auth login --device   # for headless environments (Docker, SSH, CI)

Select your organization and authorize. That's it.

If your organization hasn't enabled CLI access, you'll be prompted to send an access request to your admin. Once approved, re-run dws auth login.

1. After selecting your organization, click "Apply Now" to notify the admin
2. The admin receives a request card and can approve with one click
3. Once approved, re-run dws auth login

Go to Developer Platform → "CLI Access Management" → Enable.

For enterprise-managed scenarios, create your own DingTalk app:

1. Open Platform Console → Create App
2. Security Settings → Add redirect URLs: http://127.0.0.1,https://login.dingtalk.com
3. Publish the app
4. Login:

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

Credentials are securely persisted after first login (Keychain). Subsequent runs auto-refresh tokens.

dws can stay logged in to several DingTalk organizations at once. Each organization is one profile; the current profile decides which org a command runs against (credentials are stored per organization).

dws auth login                              # log in to another org → adds a profile (first login becomes the primary)
dws profile list                            # list logged-in orgs (primary / current marker, status)
dws profile switch <name|corpId>            # switch the default org (use - to toggle back to the previous one)
dws --profile <name|corpId> contact user search --query "..."   # run one command against a specific org, without changing the default

Cross-org reads are orchestrated by the agent rather than a built-in --all-orgs: list the profiles, run the query per org with --profile, then merge. Writes default to the current org only — confirm the target org before writing across orgs.

Copying only ~/.dws/app.json does not carry the refresh token; access tokens expire after ~2 hours. Use the official export/import flow:

# Sandbox A (already logged in)
dws auth export -o /tmp/dws-auth.tar.gz
# Or for copy/paste: dws auth export --base64 -o /tmp/dws-auth.b64

# Sandbox B
dws auth import -i /tmp/dws-auth.tar.gz
# Or: dws auth import -i /tmp/dws-auth.b64 --base64
dws auth status   # confirm "Refresh Token: valid"

The bundle includes the encrypted keychain under ~/.local/share/dws-cli (with auth-token.enc and dek) plus required ~/.dws config files.

Quick Start

dws contact user search --query "engineering"      # search contacts
dws calendar event list                            # list today's calendar events
dws doc search --query "quarterly"                 # search DingTalk Docs
dws minutes list mine                              # list AI meeting notes I created
dws drive list                                     # list DingTalk drive files
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

Full command list: docs/command-index.md — all commands with descriptions and when-to-use guidance.

Using with Agents

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

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 --query "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}'

Command Help and Schema

Product commands are compiled into the binary in static endpoint mode. Use --help and the bundled Agent Skills as the source of truth; dws schema is retained for helper-only schemas such as dev.*.

# Inspect the current compiled command surface
dws aitable record query --help

# Helper-only schema introspection
dws schema "dev app create"

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

Agent Skills

The repo ships a complete Agent Skill system under skills/, now organized into two layouts:

• skills/mono/ — single-skill layout (one SKILL.md + references/products/), recommended default.
• skills/multi/ — per-product skills (dingtalk-aitable/, dingtalk-calendar/, dingtalk-chat/, ... 22 products in total), each with its own SKILL.md. 🧪 EXPERIMENTAL / preview — see banner in each multi SKILL.md for caveats.

After installing, AI tools like Claude Code / Cursor can operate DingTalk directly through natural language:

# Install skills into current project (defaults to mono)
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).

China users: prefix DWS_GITEE_REPO to use the Gitee mirror — see China mirror.

Switching or re-installing with dws skill setup:

# Interactive: prompts for mode + target agents
dws skill setup

# Install mono skill to every detected agent home (claude / cursor / codex / opencode / qoder)
dws skill setup --mode mono --target all --yes

# Install multi skills to a single agent home
dws skill setup --mode multi --target cursor --yes

# Point at a local source tree (e.g. a fork or work-in-progress)
DWS_SKILL_SOURCE=/path/to/skills dws skill setup --mode multi

Env vars: DWS_SKILL_MODE=mono|multi (also honored by install.sh / install.ps1), DWS_SKILL_SOURCE=<path>.

What's included (mono layout):

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

Features

dws api lets you call any DingTalk OpenAPI without an SDK. Tokens are automatically acquired and refreshed.

Prerequisite: Must login with your own app credentials (see Custom App mode). Encrypted tokens from MCP default-credential login are not supported for raw API calls.

# Login (first time only)
dws auth login --client-id <APP_KEY> --client-secret <APP_SECRET>

# === api.dingtalk.com ===

# List all enterprise apps
dws api GET /v1.0/microApp/allApps

# Search users (POST + JSON body)
dws api POST /v1.0/contact/users/search \
  --data '{"queryWord":"engineering","offset":0,"size":10}'

# === oapi.dingtalk.com ===

# Get user details (use --base-url to specify domain)
dws api POST /topapi/v2/user/get \
  --base-url https://oapi.dingtalk.com \
  --data '{"userid":"<USER_ID>"}'

# Or use the full URL directly
dws api POST https://oapi.dingtalk.com/topapi/v2/user/get \
  --data '{"userid":"<USER_ID>"}'

# === General ===
dws api GET /v1.0/microApp/allApps --page-all   # auto-paginate
dws api GET /v1.0/microApp/allApps --dry-run     # preview request
dws api GET /v1.0/microApp/allApps --jq '.agentId'  # jq filtering

Built-in pipeline engine that normalizes flag names, splits sticky arguments, and fuzzy-matches typos:

# 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 --query "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 "dev app create" --jq '.tool.required'

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

dws schema                                              # static endpoint mode note
dws schema "dev app create"                             # view helper-only schema
dws schema "dev app create" --jq '.tool.required'        # view required fields

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

Note: @ is treated as the @<path> file-injection prefix only when the next character is an ASCII path-shaped character (A-Z / a-z / 0-9 / . / / / ~ / _ / -), or @- for stdin. Chat-bot payloads like --text "@所有人 周报" or --text "@张三 看一下" pass through unchanged, so literal mentions reach the API as-is.

DingTalk bot — connect a robot to your local AI

dws dev connect bridges a DingTalk robot to a local AI CLI (Claude Code / Codex / opencode / Qoder / Gemini, or any tool via --agent-cmd): @-mention the bot in a chat and it answers using your local agent, keeping per-conversation multi-turn memory.

dws dev connect --channel auto --unified-app-id <unifiedAppId>

--unified-app-id resolves clientSecret at runtime via dev app credentials get, so the secret never appears in argv (ps / journald / shell history). The legacy --robot-client-id <id> --robot-client-secret <secret> still works but the CLI will warn you.

In-chat session commands (send the bare command as the whole message — no agent turn, no tokens):

See docs/robot-quickstart.md for the full 4-step walkthrough (install → create robot → connect → add to a group).

Key Services

Full command listing with usage scenarios: docs/command-index.md. Run dws --help for the top-level tree, or dws <service> --help for any service's subcommands.

Note on chat bot: bot capabilities (send-by-bot / recall-by-bot / add-bot / send-by-webhook / bot search) are merged into the relevant chat subtrees (e.g. dws chat message send-by-bot, dws chat group members add-bot) so the agent-facing command surface stays flat and discoverable. There is no longer a separate top-level bot product.

• conference (video meetings)
• Multi-skill mode (experimental) — per-product skills under skills/multi/; opt in via dws skill setup --mode multi

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

• Command Index — every runtime command with description and when-to-use guidance
• Reference — environment variables, exit codes, output formats, shell completion
• Architecture — static endpoint pipeline, command surface, transport layer
• Open Platform App Command Routing — yulan dev app command design, MCP overlay, permission flow, and Agent routing
• Changelog — release history and migration notes

Contributing

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

License

Apache-2.0