Skip to content
Back to search

dingtalk-workspace-cli

DingTalk Workspace is an officially open-sourced cross-platform CLI tool from DingTalk. It unifies DingTalk’s full suite of product capabilities into a single package, is designed for both human users and AI agent scenarios.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/dingtalk-real-ai/dingtalk-workspace-cli with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/dingtalk-real-ai/dingtalk-workspace-cli'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dingtalk-real-ai--dingtalk-workspace-cli/badge.svg)](/listings/dingtalk-real-ai--dingtalk-workspace-cli)

HTML

<a href="/listings/dingtalk-real-ai--dingtalk-workspace-cli"><img src="/api/listings/dingtalk-real-ai--dingtalk-workspace-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**macOS / Linux:**

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

> Linux binaries are linked against glibc (baseline 2.17). musl-based distributions such as Alpine are not supported; the installer detects them and stops instead of installing a binary that cannot start.

**Windows (PowerShell):**

irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.ps1 | iex

<details> <summary><strong>Skill mode: mono vs multi</strong></summary>

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.

| Mode | What gets installed | Best for | |------|----------------------|----------| | **multi** (default) | Per-product skills (`dingtalk-aitable`, `dingtalk-calendar`, `dingtalk-chat`, ...) | Single-product tasks; smaller context per call | | **mono** (legacy) | One `dws` skill covering all products | Cross-product workflows; single entry point |

> Installs and upgrades default to `multi`. `mono` remains available via `DWS_SKILL_MODE=mono` or `dws skill setup --mode mono`. File issues if you hit problems.

How to pick:

- **Quick install** (one-liner above): non-interactive, installs `multi`. - **TTY install** (download then run): `curl -O .../install.sh && bash install.sh` — prompts `1) multi 2) mono` (default 1). - **Override via env**: `curl -fsSL ... | DWS_SKILL_MODE=mono sh`. - **Switch later**: `dws skill setup --mode mono` (or `--mode multi`) — review the listed paths and confirm interactively.

</details>

<details> <summary>Other install methods</summary>

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

npm install -g dingtalk-workspace-cli

Install the latest beta:

npm install -g dingtalk-workspace-cli@beta

**Homebrew** (macOS / Linux):

brew tap DingTalk-Real-AI/dingtalk-workspace-cli https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
brew install dingtalk-workspace-cli

> The Formula lives in this repository, so the first `tap` command must include the explicit repository URL. Afterwards, use `brew upgrade dingtalk-workspace-cli` normally.

Install the keg-only Homebrew beta without replacing the stable Formula:

brew install dingtalk-workspace-cli-beta
$(brew --prefix dingtalk-workspace-cli-beta)/bin/dws version

To make the beta `dws` the default for the current shell, prepend `$(brew --prefix dingtalk-workspace-cli-beta)/bin` to PATH.

**Pre-built binary**: download from [GitHub Releases](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases).

> **macOS users**: If you see "cannot be opened because Apple cannot check it for malicious software", run: > ```bash > 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+. On supported macOS, Linux, and Windows amd64/arm64 hosts, > the default CGO build includes the SafeChat backend without a build tag and > therefore requires a working C compiler. Set `CGO_ENABLED=0` only when a stub > build is intentional. Use `make package` with Docker to build all six release > targets through the repository's pinned cross-compilation toolchain.

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 946 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">DingTalk Workspace CLI (dws)</h1>
  2. <p align="center"><code>dws</code> — DingTalk Workspace on the command line, built for humans and AI agents.</p>
  3. <p align="center">
  4. <img src="https://img.alicdn.com/imgextra/i1/O1CN01oKAc2r28jOyyspcQt_!!6000000007968-2-tps-4096-1701.png" alt="DWS Product Overview" width="100%">
  5. </p>
  6. <p align="center">
  7. <img src="https://img.shields.io/badge/Go-1.26+-green?logo=go&logoColor=white" alt="Go 1.26+">
  8. <a href="https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue" alt="License Apache-2.0"></a>
  9. <a href="https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases"><img src="https://img.shields.io/github/v/release/DingTalk-Real-AI/dingtalk-workspace-cli?color=red&label=release" alt="Latest Release"></a>
  10. <a href="https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/actions/workflows/ci.yml"><img src="https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  11. <img src=".github/badges/coverage.svg" alt="Coverage">
  12. </p>
  13. <p align="center">
  14. <a href="./README_zh.md">中文版</a> · <a href="./README.md">English</a> · <a href="./docs/reference.md">Reference</a> · <a href="./CHANGELOG.md">Changelog</a>
  15. </p>
  16. > [!IMPORTANT]
  17. > **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](#getting-started) below.
  18. >
  19. > <img src="https://img.alicdn.com/imgextra/i1/O1CN01WJyAsJ1prD2ovQACM_!!6000000005413-2-tps-718-720.png" alt="dws Open Source Community DingTalk Group QR Code" width="150">
  20. <details>
  21. <summary><strong>Table of Contents</strong></summary>
  22. - [Why dws?](#why-dws)
  23. - [Installation](#installation)
  24. - [Upgrade](#upgrade)
  25. - [Getting Started](#getting-started)
  26. - [Quick Start](#quick-start)
  27. - [Using with Agents](#using-with-agents)
  28. - [Features](#features)
  29. - [Key Services](#key-services)
  30. - [Security by Design](#security-by-design)
  31. - [Reference & Docs](#reference--docs)
  32. - [OpenHarmony build](#openharmony-build)
  33. - [Contributing](#contributing)
  34. </details>
  35. ---
  36. <h2 id="why-dws">Why dws?</h2>
  37. - **For humans** — `--help` for usage, `--dry-run` to preview requests, `-f table/json/raw` for output formats.
  38. - **For AI agents** — structured JSON responses + built-in Agent Skills, ready out of the box.
  39. - **For enterprise admins** — zero-trust architecture: OAuth device-flow auth + domain allowlisting + least-privilege scoping. **Not a single byte can bypass authentication and audit.**
  40. ## Installation
  41. **macOS / Linux:**
  42. ```bash
  43. curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh
  44. ```
  45. > Linux binaries are linked against glibc (baseline 2.17). musl-based distributions such as Alpine are not supported; the installer detects them and stops instead of installing a binary that cannot start.
  46. **Windows (PowerShell):**
  47. ```powershell
  48. irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.ps1 | iex
  49. ```
  50. <details>
  51. <summary><strong>Skill mode: mono vs multi</strong></summary>
  52. 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.
  53. | Mode | What gets installed | Best for |
  54. |------|----------------------|----------|
  55. | **multi** (default) | Per-product skills (`dingtalk-aitable`, `dingtalk-calendar`, `dingtalk-chat`, ...) | Single-product tasks; smaller context per call |
  56. | **mono** (legacy) | One `dws` skill covering all products | Cross-product workflows; single entry point |
  57. > Installs and upgrades default to `multi`. `mono` remains available via `DWS_SKILL_MODE=mono` or `dws skill setup --mode mono`. File issues if you hit problems.
  58. How to pick:
  59. - **Quick install** (one-liner above): non-interactive, installs `multi`.
  60. - **TTY install** (download then run): `curl -O .../install.sh && bash install.sh` — prompts `1) multi 2) mono` (default 1).
  61. - **Override via env**: `curl -fsSL ... | DWS_SKILL_MODE=mono sh`.
  62. - **Switch later**: `dws skill setup --mode mono` (or `--mode multi`) — review the listed paths and confirm interactively.
  63. </details>
  64. <details>
  65. <summary>Other install methods</summary>
  66. **npm** (requires Node.js (npm/npx)):
  67. ```bash
  68. npm install -g dingtalk-workspace-cli
  69. ```
  70. Install only the CLI binary and skip all bundled Skill validation, extraction,
  71. Agent-directory updates, state writes, and user-cache refreshes:
  72. ```bash
  73. DWS_NO_SKILLS=1 npm install -g dingtalk-workspace-cli
  74. ```
  75. ```powershell
  76. $env:DWS_NO_SKILLS = "1"
  77. npm install -g dingtalk-workspace-cli
  78. ```
  79. Without `DWS_NO_SKILLS=1`, npm keeps installing Skills as before. A failure
  80. while refreshing the optional `~/.dws/skills` cache is reported as a warning
  81. after the CLI and Agent Skills are installed; run `dws skill setup` to refresh
  82. Skills later.
  83. Install the latest beta:
  84. ```bash
  85. npm install -g dingtalk-workspace-cli@beta
  86. ```
  87. **Homebrew** (macOS / Linux):
  88. ```bash
  89. brew tap DingTalk-Real-AI/dingtalk-workspace-cli https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
  90. brew install dingtalk-workspace-cli
  91. ```
  92. > The Formula lives in this repository, so the first `tap` command must include the explicit repository URL. Afterwards, use `brew upgrade dingtalk-workspace-cli` normally.
  93. Install the keg-only Homebrew beta without replacing the stable Formula:
  94. ```bash
  95. brew install dingtalk-workspace-cli-beta
  96. $(brew --prefix dingtalk-workspace-cli-beta)/bin/dws version
  97. ```
  98. To make the beta `dws` the default for the current shell, prepend `$(brew --prefix dingtalk-workspace-cli-beta)/bin` to PATH.
  99. **Pre-built binary**: download from [GitHub Releases](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases).
  100. > **macOS users**: If you see "cannot be opened because Apple cannot check it for malicious software", run:
  101. > ```bash
  102. > xattr -d com.apple.quarantine /path/to/dws
  103. > ```
  104. **Build from source**:
  105. ```bash
  106. git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
  107. cd dingtalk-workspace-cli
  108. go build -o dws ./cmd # build to current directory
  109. cp dws ~/.local/bin/ # install to PATH
  110. ```
  111. Static endpoint data is generated from the Wukong baseline and committed in this
  112. repository under `internal/syncdata`, so source builds do not require a sibling
  113. data checkout.
  114. > Requires Go 1.26+. On supported macOS, Linux, and Windows amd64/arm64 hosts,
  115. > the default CGO build includes the SafeChat backend without a build tag and
  116. > therefore requires a working C compiler. Set `CGO_ENABLED=0` only when a stub
  117. > build is intentional. Use `make package` with Docker to build all six release
  118. > targets through the repository's pinned cross-compilation toolchain.
  119. </details>
  120. ## OpenHarmony build
  121. The repository supports an `openharmony/arm64` build with a Go 1.26.7
  122. OpenHarmony toolchain. Every beta and stable release builds, self-signs,
  123. verifies, and publishes `dws-openharmony-arm64.tar.gz` alongside the six
  124. platform archives, and the binary has been validated on a HarmonyOS PC.
  125. ```bash
  126. OHOS_GO=/path/to/openharmony-go \
  127. DWS_PACKAGE_VERSION=1.2.3 \
  128. ./scripts/dev/build-openharmony.sh
  129. # Or create a self-signed package archive (dws-openharmony-arm64.tar.gz):
  130. OHOS_GO=/path/to/openharmony-go \
  131. DWS_PACKAGE_VERSION=1.2.3 \
  132. ./scripts/dev/package-openharmony.sh
  133. ```
  134. The build is `CGO_ENABLED=0` and therefore keeps SafeChat unavailable. Runtime
  135. native payloads are also unsupported on OpenHarmony. The script verifies the
  136. resulting static AArch64 ELF and its Go build metadata; see
  137. [`docs/openharmony.md`](docs/openharmony.md) for the complete boundary.
  138. ## China mirror
  139. For users in mainland China, the following channels avoid GitHub network issues. By default (without setting these environment variables) the installer pulls from GitHub.
  140. **1. Install script + pre-built binary (Gitee mirror):**
  141. Repository mirror: `https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli`
  142. ```bash
  143. curl -fsSL https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli/raw/main/scripts/install.sh | DWS_GITEE_REPO=DingTalk-Real-AI/dingtalk-workspace-cli sh
  144. ```
  145. > 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.
  146. **2. npm package (npmmirror mirror):**
  147. ```bash
  148. npm install -g dingtalk-workspace-cli --registry=https://registry.npmmirror.com
  149. ```
  150. > npmmirror automatically syncs public packages from the public npm registry, so this works directly in China.
  151. **3. Skills only (Gitee mirror):**
  152. ```bash
  153. curl -fsSL https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli/raw/main/scripts/install-skills.sh | DWS_GITEE_REPO=DingTalk-Real-AI/dingtalk-workspace-cli sh
  154. ```
  155. > 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.
  156. ## Upgrade
  157. > Requires **v1.0.7** or later. For earlier versions, please re-run the [install script](#installation) to upgrade.
  158. DWS 默认通过 npm Registry 查询发行版本。官方开源版独立二进制从同版本 GitHub Release 下载当前平台归档和技能包,校验后自更新,无需安装 npm;npm、pnpm 和 Homebrew 安装交由对应包管理器升级。详见[版本来源与升级方式](docs/upgrading.md)。
  159. ```bash
  160. dws upgrade # interactive upgrade to latest version
  161. dws upgrade --check # check for new versions without installing
  162. dws upgrade --list # list stable release versions
  163. dws upgrade --beta # upgrade to the latest beta pre-release
  164. dws upgrade --check --beta # check the beta track without installing
  165. dws upgrade --list --beta # list beta pre-release versions
  166. dws upgrade --version v1.0.7 # upgrade to a specific version
  167. dws upgrade --version v1.0.8-beta.1 # upgrade to a specific beta version
  168. dws upgrade --rollback # rollback to the previous version
  169. dws upgrade -y # skip confirmation prompt
  170. ```
  171. `dws upgrade` 默认选择正式渠道;`--beta` 选择 npm 的 beta 渠道。显式配置的 GitHub 升级来源仍使用原有协议。
  172. `auth status`、`version` 和 `--version` 也会显示版本检查结果;未知命令或参数报错时,发现新版会提示升级。检查不会自动安装软件,详见[版本检查与升级提示](docs/version-checks.md)。
  173. ### Six-channel post-release verification
  174. Maintainers and release validators can run the release-quality smoke checks for curl, PowerShell, npm stable, npm beta, Homebrew, and `dws upgrade`:
  175. ```bash
  176. git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git /tmp/dws-verify
  177. cd /tmp/dws-verify/verify
  178. bash verify-all-channels.sh
  179. ```
  180. The verifier uses isolated directories and does not replace the `dws` on the current PATH. It reports `PASS`, `FAIL`, and `SKIP`; a platform skip is not a pass and must be covered on the matching host. See [`verify/README.md`](verify/README.md) for the platform matrix.
  181. <details>
  182. <summary><strong>How it works</strong></summary>
  183. 独立二进制的升级分为准备和替换两阶段:
  184. 1. **准备** — 官方开源版下载同版本的当前平台归档和技能包,强制验证大小、SHA256 及新二进制版本。自定义 Registry 保留完整 npm 包及完整性校验。验证失败时不替换现有安装。
  185. 2. **Apply** — only after all preparations succeed, the binary is replaced and skills are flattened into the canonical `~/.agents/skills` root. Agents classified by the pinned compatibility registry as supporting the universal root read it directly; other detected Agents receive links to the canonical copy, with a direct-copy fallback when links are unavailable. Older DWS-managed agent-specific copies are backed up and retired so the same Skill is not discovered twice.
  186. 独立二进制升级保留自动备份和 `dws upgrade --rollback`。包管理器安装的回退由对应管理器处理;npm/pnpm 没有 `--skip-skills` 参数,但可设置 `DWS_NO_SKILLS=1` 仅安装 CLI 二进制。Homebrew 捆绑技能,使用 `dws skill setup` 安装到 Agent 目录。
  187. | Flag | Description |
  188. |------|-------------|
  189. | `--check` | Check for updates without installing |
  190. | `--list` | List available stable release versions with changelogs |
  191. | `--beta` | Use the beta pre-release track for `upgrade`, `--check`, or `--list` |
  192. | `--version` | Upgrade to a specific version (e.g. `v1.0.7` or `v1.0.8-beta.1`) |
  193. | `--rollback` | Rollback to the previous backed-up version |
  194. | `--force` | Force reinstall even if already on the latest version |
  195. | `--skip-skills` | Skip skill package update |
  196. | `-y` | Skip confirmation prompt |
  197. </details>
  198. ## Getting Started
  199. ```bash
  200. dws auth login # browser opens automatically
  201. dws auth login --device # for headless environments (Docker, SSH, CI)
  202. ```
  203. Select your organization and authorize. That's it.
  204. > 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`.
  205. <details>
  206. <summary><strong>Organization hasn't enabled CLI access?</strong></summary>
  207. 1. After selecting your organization, click "Apply Now" to notify the admin
  208. 2. The admin receives a request card and can approve with one click
  209. 3. Once approved, re-run `dws auth login`
  210. <p align="center">
  211. <img src="https://img.alicdn.com/imgextra/i2/O1CN01wtsYuQ1CTbboVTlsD_!!6000000000082-2-tps-2696-1544.png" alt="Apply for Access" width="600">
  212. </p>
  213. </details>
  214. <details>
  215. <summary><strong>Admin: Enable CLI access for your organization</strong></summary>
  216. Go to [Developer Platform](https://open-dev.dingtalk.com) → "CLI Access Management" → Enable.
  217. <p align="center">
  218. <img src="https://img.alicdn.com/imgextra/i4/O1CN01M8K7Wj1rZ0WikrZby_!!6000000005644-2-tps-2940-1596.png" alt="CLI Access Management" width="600">
  219. </p>
  220. </details>
  221. <details>
  222. <summary><strong>Custom App mode (CI/CD, ISV integration)</strong></summary>
  223. For enterprise-managed scenarios, create your own DingTalk app:
  224. 1. [Open Platform Console](https://open-dev.dingtalk.com/fe/app#/corp/app) → Create App
  225. 2. Security Settings → Add redirect URLs: `http://127.0.0.1,https://login.dingtalk.com`
  226. 3. Publish the app
  227. 4. Login:
  228. ```bash
  229. dws auth login --client-id <your-app-key> --client-secret <your-app-secret>
  230. ```
  231. Credentials are securely persisted after first login (Keychain). Subsequent runs auto-refresh tokens.
  232. </details>
  233. <details>
  234. <summary><strong>Multiple organizations (profiles)</strong></summary>
  235. `dws` can stay logged in to several DingTalk accounts at once, including multiple accounts in the same organization. A profile is uniquely identified by `corpId:userId`; the current profile decides which identity a command runs as.
  236. Business commands automatically check and refresh local OAuth credentials as needed;
  237. there is no need to run `auth status` before each request. `auth status` retains
  238. refresh, migration and repair behavior and may wait for the authentication lock.
  239. For concurrent polling, use `dws auth status --readonly --format json` (optionally with
  240. `--profile`): it reads a local snapshot without the authentication lock, network
  241. validation, refresh, migration or credential writes. System Keychain reads can
  242. still wait. Both modes use the same output fields. A read-only result with a
  243. non-empty `reason` is inconclusive and must not be treated as a confirmed logout;
  244. `local_state_requires_repair` signals migration/repair and `local_state_unreadable`
  245. signals a failed local read. Use `auth status` without `--readonly` with the same
  246. profile for refresh or repair. Read-only mode never reports a refresh and may
  247. report an expired access token that normal mode would refresh.
  248. Concurrent updates may yield an older snapshot or an inconclusive result.
  249. In both modes, `authenticated` is true when either the access or refresh
  250. credential is valid; `token_valid` separately describes access-token usability.
  251. ```bash
  252. dws auth login # add or refresh one account
  253. dws profile list # list every logged-in account
  254. dws profile switch <corpId:userId> # persistently switch; use - to toggle back
  255. dws profile switch "<corpName>:<userName>" # friendly input; names must be unique
  256. dws --profile <corpId> contact user search --query "..." # use that org's explicitly recorded current account
  257. dws --profile <corpId:userId> contact user search --query "..." # use one exact account without changing the default
  258. ```
  259. Selectors support `corpId:userId`, `corpId:userName`, `corpName:userId`, and `corpName:userName`. Friendly names are input aliases only; use the stable `profile` value returned by `profile list` for automation. Duplicate organization or account names fail with explicit `corpId:userId` candidates. If an organization has multiple accounts but no recorded current account, `--profile <corpId>` fails instead of choosing the first or most recently used account.
  260. `currentProfile`, `previousProfile`, and per-organization defaults are stored as exact identities. `primaryProfile` remains in JSON only for compatibility and is not used for selection. `profile list` reads status and expiry from each real identity Token without refreshing it. `auth logout --profile <corpId>` removes all local accounts in that organization; an exact selector or local profile name removes one account.
  261. Cross-org reads are orchestrated by the agent rather than a built-in `--all-orgs`: list profiles, group by `corpId`, and use the unique `isOrgCurrent=true` account for each organization. If a multi-account organization has no default, ask the user to choose an account first. Writes default to the current account — confirm both organization and account before cross-org writes.
  262. On macOS, transient or unclassified Keychain read failures block a new OAuth login rather than risking a mixed Keychain/file-DEK state. A confirmed missing DEK or ciphertext/DEK mismatch is preserved through authorization and replaced only for the slots targeted by the fresh login. If normal terminal commands can still read the login while a sandbox using `DWS_DISABLE_KEYCHAIN=1` cannot, migrate the legacy and profile auth entries without exposing tokens:
  263. ```bash
  264. env -u DWS_DISABLE_KEYCHAIN dws auth migrate-keychain --to file-dek --dry-run --format json
  265. env -u DWS_DISABLE_KEYCHAIN dws auth migrate-keychain --to file-dek --yes --format json
  266. DWS_DISABLE_KEYCHAIN=1 dws auth status --format json
  267. ```
  268. The migration validates every selected auth ciphertext before writing, ignores unrelated application secrets, and can be rerun after an interrupted commit. If validation identifies genuinely damaged ciphertext, remove only the affected account with `dws auth logout --profile <corpId:userId>`, or all accounts in one organization with `--profile <corpId>`, then log in again. Use `dws auth reset` only when you intend to discard every local profile.
  269. </details>
  270. <details>
  271. <summary><strong>Migrate auth between Linux sandboxes</strong></summary>
  272. Copying only `~/.dws/app.json` does not carry the refresh token; access tokens expire after ~2 hours. Use the official export/import flow:
  273. ```bash
  274. # Sandbox A (already logged in)
  275. dws auth export -o /tmp/dws-auth.tar.gz
  276. # Or for copy/paste: dws auth export --base64 -o /tmp/dws-auth.b64
  277. # Sandbox B
  278. dws auth import -i /tmp/dws-auth.tar.gz
  279. # Or: dws auth import -i /tmp/dws-auth.b64 --base64
  280. dws auth status # confirm "Refresh Token: valid"
  281. ```
  282. The bundle includes the encrypted keychain under `~/.local/share/dws-cli` (with `auth-token.enc` and `dek`) plus required `~/.dws` config files.
  283. Windows export and import are intentionally rejected before credentials or
  284. bundles are read: Windows stores credentials as DPAPI-protected HKCU Registry
  285. values, and the current file-DEK bundle has no safe DPAPI-to-portable conversion.
  286. </details>
  287. ## Quick Start
  288. ```bash
  289. dws contact user search --query "engineering" # search contacts
  290. dws calendar event list # list today's calendar events
  291. dws doc search --query "quarterly" # search DingTalk Docs
  292. dws whiteboard +query --node "<whiteboard-node-id>" --view summary --format json # inspect a whiteboard
  293. dws minutes list mine # list AI meeting notes I created
  294. dws drive list # list DingTalk drive files
  295. dws todo task create --title "Quarterly report" --executors "<your-userId>" # create a todo (replace <your-userId>)
  296. dws todo task list --dry-run # preview without executing
  297. ```
  298. > **Full command list**: [`docs/command-index.md`](./docs/command-index.md) — all commands with descriptions and when-to-use guidance.
  299. ### Whiteboards
  300. Use `dws whiteboard` for standalone whiteboards and whiteboards embedded in documents: query content, create / update with OpenNodes, preview changes with `+diff`, render local SVG previews, and manage personal / team templates or use public templates.
  301. ```bash
  302. dws whiteboard --help
  303. dws whiteboard render --source @whiteboard.json --output ./whiteboard-preview.svg --format json
  304. dws whiteboard +diff --help
  305. dws whiteboard template personal list --format json
  306. dws whiteboard template team list --template-workspace "<workspace-id>" --page-all --format json
  307. dws whiteboard template public list --query "retrospective" --format json
  308. ```
  309. `whiteboard.json` is an OpenNodes source file. SVG rendering is a local preview; review its fidelity and warnings, then confirm the current preview before creating the whiteboard. Use `+diff` to inspect the proposed update before `+update`. For template `save` / `create` commands, `--dry-run` performs an optional server-side preflight without saving a template or creating a whiteboard.
  310. See the [whiteboard reference](./skills/mono/references/products/whiteboard.md), [Diff guide](./skills/mono/references/products/whiteboard/diff.md), and [SVG preview guide](./skills/mono/references/products/whiteboard/render.md).
  311. ## Using with Agents
  312. dws is designed as an AI-native CLI. Complete [Installation](#installation) and [Getting Started](#getting-started) first, then install Agent Skills:
  313. ```bash
  314. npx skills add DingTalk-Real-AI/dingtalk-workspace-cli -g
  315. ```
  316. The installer first shows the plan — which skills, which target directories, and how existing same-named skills will be handled — and asks for confirmation before writing anything. `dws skill setup` remains the power-user / China / upgrade path. See [Agent Skills](#agent-skills).
  317. ### Agent Invocation Patterns
  318. ```bash
  319. # Use --yes to skip confirmation prompts (required for agents)
  320. dws todo task create --title "Review PR" --executors "<your-userId>" --yes
  321. # Use --dry-run to preview operations (safe execution)
  322. dws contact user search --query "engineering" --dry-run
  323. # Use --jq to extract precisely (save tokens)
  324. dws contact user get-self --jq '.result[0].orgEmployeeModel | {name: .orgUserName, dept: .depts[0].deptName, userId}'
  325. ```
  326. ### Command Help and Schema
  327. Use Cobra help and Schema for different parts of the command contract:
  328. - `dws <path> --help` is the source of truth for whether a command exists and which flags the binary accepts.
  329. - `dws schema "<path>" --compact` is the normative Agent view for command selection, CLI parameters and constraints, risk, and confirmation; use a full leaf with a narrow `--jq` projection for mapping or provenance audits.
  330. - If Help and Schema disagree, treat it as contract drift: pass only flags accepted by Cobra and use the more conservative safety semantics.
  331. - Schema describes commands; it does not read or search DingTalk business data. Execute the real product command after discovery.
  332. ```bash
  333. # Confirm that the command exists and inspect accepted flags
  334. dws aitable record query --help
  335. # Discover within a product, then inspect the selected leaf contract
  336. dws schema aitable --compact
  337. dws schema "aitable record query" --compact
  338. # Execute the real business query
  339. dws aitable record query --base-id BASE_ID --table-id TABLE_ID --limit 10
  340. ```
  341. `dws schema --all` exports the complete contract for tooling, CI, audits, and compatibility baselines. Agents should query progressively with `--compact`; its positive field allowlist prevents new full/audit fields from silently expanding Agent context.
  342. ### Agent Skills
  343. ```bash
  344. npx skills add DingTalk-Real-AI/dingtalk-workspace-cli -g
  345. ```
  346. This discovers `skills/multi/dingtalk-*/SKILL.md` (catalog layout, three levels under `skills/`, the depth `npx skills add` already walks) and installs `dingtalk-calendar`, `dingtalk-chat`, … into the agent directories [vercel-labs/skills](https://github.com/vercel-labs/skills) already knows: project `.agents/skills/` by default, user-global `.agents/skills` with `-g`, plus links into `~/.cursor/skills`, `~/.claude/skills`, and the other registered homes.
  347. Without `-y`, the installer lists the skills, target directories, and existing same-named content handling for confirmation before it writes. Keep that prompt for interactive and first-time global installs. `-y` exists for automation only: add it after the user has explicitly confirmed the install targets and overwrite behavior — this path does not maintain `dws skill setup`'s ownership, backup, or mono↔multi mutual-exclusion cleanup state, so a skipped prompt can replace user files without consent.
  348. The all-in-one mono skill (`skills/mono`, frontmatter name `dws`) is marked `metadata.internal: true`, so it is **not** a default installable skill. Agents therefore do not double-route between `dws` and the per-product skills.
  349. `dws skill setup` remains the power-user / China / upgrade path. It still owns Gitee fallback, upgrade-time skill refresh, ownership in `~/.dws/skills-state.json`, and mono↔multi mutual-exclusion cleanup.
  350. The repo ships two source trees:
  351. - `skills/multi/` — per-product skills (`dingtalk-aitable/`, `dingtalk-calendar/`, `dingtalk-chat/`, ...), each with its own `SKILL.md`. Default for both `npx skills add` and `dws skill setup`.
  352. - `skills/mono/` — single-skill layout (one `SKILL.md` + `references/products/`), legacy. Hidden from `npx skills add`. Still installed by `dws skill setup --mode mono` and the curl / zip installers.
  353. Leaf safety/parameters/selection prose for Schema generation come from ProductDecl / ContractFinal declarations in Go. The former `internal/cli/schema_hints/` HintFile tree is fully retired and must not reappear.
  354. After installing, AI tools like Claude Code / Cursor can operate DingTalk directly through natural language.
  355. > China users: `npx skills add` clones from GitHub. Prefer `dws skill setup` or prefix `DWS_GITEE_REPO` on `install-skills.sh` — see [China mirror](#china-mirror).
  356. **Power-user / China / upgrade: `dws skill setup`**
  357. ```bash
  358. # Interactive: prompts for mode + target agents
  359. dws skill setup
  360. # Preview the exact directories that mono setup would back up and replace
  361. dws skill setup --mode mono --target all --dry-run
  362. # Run interactively and confirm the listed directories
  363. dws skill setup --mode mono --target all
  364. # Preview, then install multi skills to a single agent home with interactive confirmation
  365. dws skill setup --mode multi --target cursor --dry-run
  366. dws skill setup --mode multi --target cursor
  367. # Point at a local source (an extracted dws-skills.zip root, its multi/ directory, or a source checkout), preview first
  368. DWS_SKILL_SOURCE=/absolute/path/to/extracted-dws-skills dws skill setup --mode multi --dry-run
  369. DWS_SKILL_SOURCE=/absolute/path/to/extracted-dws-skills dws skill setup --mode multi
  370. ```
  371. | Flag | Values | Description |
  372. |------|--------|-------------|
  373. | `--mode` | `mono` \| `multi` | Skill layout; defaults to interactive prompt |
  374. | `--target` | `all` \| `claude` \| `cursor` \| `codex` \| `zcode` \| `opencode` \| `qoder` | Where to install; `all` covers every detected agent home, including ZCode at `~/.zcode/skills` |
  375. | `--source` | path | Local source directory (overrides bundled skills); accepts a mode directory, an extracted `dws-skills.zip` root, or a source checkout containing `skills/` |
  376. | `--yes` | — | Scripting-only: skip the confirmation prompt. Removals are still backed up to `~/.dws/skill-backups/` first |
  377. > The setup command can remove the opposite-mode layout (`dws/` for multi, DWS-managed multi Skills for mono) and stale managed Skills not in the bundle. DWS records ownership, installer version, source, and content digest centrally in `~/.dws/skills-state.json` (or `$DWS_CONFIG_DIR/skills-state.json`). Exact official names shipped before the centralized state remain a frozen migration list. A `dingtalk-*` prefix alone never authorizes cleanup, so other same-prefix market/user Skills are preserved. Every removal is previewed before confirmation and preserved under `~/.dws/skill-backups/<timestamp>/`; a directory that cannot be backed up is never removed. In a non-interactive shell, first run `--dry-run` and inspect its output; only then may the caller explicitly choose the scripting-only confirmation bypass.
  378. After a multi setup or upgrade, DWS stores the official bundle snapshot and centralized ownership metadata in `~/.dws/skills-state.json` (or `$DWS_CONFIG_DIR/skills-state.json`). Every upgrade installs and overwrites the complete bundled Skill set from that release. Deleting or excluding a bundled Skill is not sticky: the next upgrade restores it. `dws upgrade --force` additionally allows reinstalling the current CLI version when no newer version is available.
  379. Env vars: `DWS_NO_SKILLS=1` (npm, `install.sh`, and `install.ps1`; skips the complete Skill path), `DWS_SKILL_MODE=mono|multi` (also honored by `install.sh` / `install.ps1`), `DWS_SKILL_SOURCE=<path>`.
  380. **What's included (mono layout):**
  381. | Component | Path | Description |
  382. |-----------|------|-------------|
  383. | Master Skill | `skills/mono/SKILL.md` | Intent routing, decision tree, safety rules, error handling |
  384. | Product references | `skills/mono/references/products/*.md` | Per-product command reference (aitable, chat, calendar, etc.) |
  385. | Intent guide | `skills/mono/references/intent-guide.md` | Disambiguation for confusing scenarios (e.g. report vs todo) |
  386. | Global reference | `skills/mono/references/global-reference.md` | Auth, output formats, global flags |
  387. | Error codes | `skills/mono/references/error-codes.md` | Error codes + debugging workflows |
  388. | Ready-made scripts | `skills/mono/scripts/*.py` | 13 batch operation scripts (see below) |
  389. <details>
  390. <summary><strong>Ready-made scripts</strong> — 13 Python scripts for common multi-step workflows</summary>
  391. | Script | Description |
  392. |--------|-------------|
  393. | `calendar_schedule_meeting.py` | Create event + add participants + find & book available meeting room |
  394. | `calendar_free_slot_finder.py` | Find common free slots across multiple people, recommend best meeting time |
  395. | `calendar_today_agenda.py` | View today/tomorrow/this week's schedule |
  396. | `import_records.py` | Batch import records from CSV/JSON into AITable |
  397. | `bulk_add_fields.py` | Batch add fields to an AITable data table |
  398. | `upload_attachment.py` | Upload attachment to AITable attachment field |
  399. | `todo_batch_create.py` | Batch create todos from JSON (with priority, due date, executors) |
  400. | `todo_daily_summary.py` | Summarize today/this week's incomplete todos |
  401. | `todo_overdue_check.py` | Scan overdue todos and output overdue list |
  402. | `contact_dept_members.py` | Search department by name and list all members |
  403. | `attendance_my_record.py` | View my attendance records for today/this week/specific date |
  404. | `attendance_team_shift.py` | Query team shift schedules and attendance statistics |
  405. | `report_inbox_today.py` | View today's received reports with details |
  406. </details>
  407. **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)**.
  408. ## Features
  409. <details>
  410. <summary><strong>Personal Event Subscription</strong> — real-time DingTalk messages for event-driven agents</summary>
  411. `dws event consume` subscribes as the currently logged-in user over a managed Stream WebSocket and emits each event as one NDJSON line on stdout. The 33-event public catalog covers scoped and all one-to-one/group messages, specified senders, read/recall/reaction events, group lifecycle events, seven OA approval task/instance events, one VoIP invitation event, three Todo task lifecycle events, the interactive-card callback event, two contact friend events, two Minutes events (task created and summary generated), and one personal-calendar event covering primary-calendar creation/participation, updates, and cancellations. Calendar delivery requires event registration and calendar routing on the platform; a visible CLI catalog entry does not prove availability in the current environment. Production readiness and pre-release update/cancellation delivery remain unverified.
  412. The default `ndjson`, `json`, and `pretty` output preserves the transport envelope (`type`, `event_type`, string `data`, and `headers`) for existing scripts; `compact` retains its existing processor. Add `--flatten` to emit the stable top-level business fields used by Agent workflows. `--format` controls JSON serialization; `--flatten` controls the data structure and cannot be combined with `-f raw` or `--debug-raw-events`.
  413. > **Prerequisite**: run `dws auth login`. Personal identity is resolved from the OAuth token and cannot be supplied through command-line identity flags.
  414. For an event-focused installation, use the official convenience installer:
  415. ```bash
  416. curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-event.sh | sh
  417. # Or install the standalone multi skill from an existing dws installation
  418. dws skill setup --mode multi -s event
  419. ```
  420. ```bash
  421. # Inspect the public personal event catalog and schema
  422. dws event list
  423. dws event schema user_im_message_receive_o2o --flatten
  424. dws event list --category oa
  425. dws event schema user_oa_approval_task_created --flatten
  426. dws event list --category card
  427. dws event schema user_card_action_triggered --flatten
  428. dws event list --category minutes
  429. dws event schema user_minutes_summary_generated --flatten
  430. dws event list --category todo
  431. dws event schema user_todo_task_create --flatten
  432. dws event list --category calendar
  433. dws event schema user_calendar_event_changed --flatten
  434. # Listen for primary-calendar creation, updates, and cancellations
  435. dws event consume user_calendar_event_changed --calendar-ids primary --change-types eventCreated,eventUpdated,eventCancelled --flatten --duration 10m -f ndjson
  436. # Listen for messages that mention the current user
  437. dws event +listen-im --kind at-me -f ndjson
  438. # Listen for messages from a specified sender
  439. dws event +listen-im --kind sender --user <userId> -f ndjson
  440. # Listen by openDingtalkId (external contact, bot, or cross-organization identity)
  441. dws event +listen-im --kind sender --open-dingtalk-id <openDingtalkId> -f ndjson
  442. # Listen for messages in a specified group
  443. dws event +listen-im --kind group --chat-id <openConversationId> -f ndjson
  444. # Listen for all one-to-one or all group messages
  445. dws event +listen-im --kind all-direct -f ndjson
  446. dws event +listen-im --kind all-group -f ndjson
  447. # Listen for a specified group's title changes, member changes, or disband event
  448. dws event consume user_im_group_updated --group <openConversationId> --flatten -f ndjson
  449. dws event consume user_im_group_member_added --group <openConversationId> --flatten -f ndjson
  450. dws event consume user_im_group_member_exited --group <openConversationId> --flatten -f ndjson
  451. dws event consume user_im_group_disbanded --group <openConversationId> --flatten -f ndjson
  452. # Listen for messages, reads, and recalls from the same sender in one process
  453. dws event +listen-im --kind sender --user <userId> \
  454. --events message,read,recall -f ndjson
  455. # Listen for all seven public OA approval events in one process
  456. dws event consume \
  457. user_oa_approval_task_created \
  458. user_oa_approval_task_finished \
  459. user_oa_approval_task_redirected \
  460. user_oa_approval_instance_started \
  461. user_oa_approval_instance_cc \
  462. user_oa_approval_instance_terminated \
  463. user_oa_approval_instance_finished \
  464. --flatten -f ndjson
  465. # Listen for Todo create/update/delete events where the current user is an executor
  466. dws event consume \
  467. user_todo_task_create \
  468. user_todo_task_update \
  469. user_todo_task_delete \
  470. --role-types executor \
  471. --flatten -f ndjson
  472. # Listen for interactive-card callbacks; the schema documents reviewed fields while preserving extensions
  473. dws event consume user_card_action_triggered --flatten -f ndjson
  474. # Listen for generated Minutes summaries; events carry task_uuid only, read content with dws minutes
  475. dws event consume user_minutes_summary_generated --flatten --duration 10m -f ndjson
  476. dws minutes get summary --id <task_uuid>
  477. # Inspect local consumers and cancel a subscription
  478. dws event status
  479. dws event stop <subscribe_id>
  480. ```
  481. The structured interactive-card context is at `payload.body.actionData.context`. Join `questions[].id` to `answers[question_id]`, then resolve IDs in `selected` through the same question's `options[].id`; an empty `selected` is a valid no-selection state. JSON strings in `body.context` are compatibility fallbacks, and every payload level continues to preserve unknown fields.
  482. For one-to-one and specified-sender events, use exactly one target identity: `--user` for an internal `userId`, or `--open-dingtalk-id` for an `openDingtalkId`. The CLI does not infer or convert between these identity types.
  483. | Feature | Details |
  484. |---------|---------|
  485. | Managed lifecycle | `consume` creates or reuses the personal subscription; `stop` cancels it and cleans local state |
  486. | Shared connection | Consumers for the same user share one local bus and cloud connection |
  487. | Multi-event process | One consume process can listen for compatible events for the same target while retaining one subscription per event |
  488. | Subscription isolation | Normal consumers match both event type and `subscribe_id` |
  489. | Agent-friendly output | Stream events are written to stdout as NDJSON; status and diagnostics use stderr |
  490. | Observability | `status` shows remote subscriptions, the personal bus, and local consumers |
  491. | Cross-platform | Unix Socket on macOS/Linux, Windows Named Pipe on Windows |
  492. See `skills/multi/dingtalk-event/SKILL.md` for the Agent workflow and supported event parameters.
  493. </details>
  494. <details>
  495. <summary><strong>Raw API Access</strong> — call App Token-capable server-side DingTalk OpenAPIs directly</summary>
  496. `dws api` lets you call server-side DingTalk OpenAPIs that support an internal-app App Token, without an SDK. Tokens are automatically acquired and refreshed.
  497. > **Prerequisite**: Provide one complete custom-app Client ID/Client Secret pair through one-shot flags, environment variables, or app config saved by a successful login (see [Custom App mode](#getting-started)). MCP default-credential login alone does not support Raw API calls.
  498. Client ID and Client Secret are resolved only as one complete pair, in this order: complete `--client-id/--client-secret` > complete `DWS_CLIENT_ID/DWS_CLIENT_SECRET` > complete app config. A half-configured source fails explicitly and is never combined with another source. Flags/env used directly by `dws api` are one-shot and do not persist the App Secret; flags/env used by a successful `dws auth login` are persisted as that exact pair for OAuth refresh and later Raw API calls. The acquired App Token is cached under `app-token:<clientID>`; the hidden `--token` accepts a temporary caller-supplied App Token and neither persists nor refreshes it.
  499. Client Secrets use the canonical Keychain slot `appsecret:<clientID>`, distinct from OAuth User Tokens and App Tokens. Existing plaintext app config and historical `client-secret:<clientID>` entries are migrated automatically. If the old and new slots disagree, DWS fails closed and asks for a new login instead of guessing.
  500. ```bash
  501. # Login (first time only)
  502. dws auth login --client-id <APP_KEY> --client-secret <APP_SECRET>
  503. # Or use one environment pair; a complete env pair overrides app config atomically
  504. export DWS_CLIENT_ID=<APP_KEY>
  505. export DWS_CLIENT_SECRET=<APP_SECRET>
  506. # === api.dingtalk.com ===
  507. # List all enterprise apps
  508. dws api GET /v1.0/microApp/allApps
  509. # Search users (POST + JSON body)
  510. dws api POST /v1.0/contact/users/search \
  511. --data '{"queryWord":"engineering","offset":0,"size":10}'
  512. # === oapi.dingtalk.com ===
  513. # Get user details (use --base-url to specify domain)
  514. dws api POST /topapi/v2/user/get \
  515. --base-url https://oapi.dingtalk.com \
  516. --data '{"userid":"<USER_ID>"}'
  517. # Or use the full URL directly
  518. dws api POST https://oapi.dingtalk.com/topapi/v2/user/get \
  519. --data '{"userid":"<USER_ID>"}'
  520. # === General ===
  521. dws api GET /v1.0/microApp/allApps --dry-run # preview request
  522. dws api GET /v1.0/microApp/allApps --jq '.appList | length' # jq filtering
  523. # Read a JSON body from a file (--params also accepts @file; use - for stdin)
  524. dws api POST https://oapi.dingtalk.com/topapi/v2/department/listsubid \
  525. --data @department-request.json --dry-run
  526. # Stream one multipart file; top-level --data fields become text form fields; review a dry-run first
  527. dws api POST https://oapi.dingtalk.com/media/upload \
  528. --data '{"type":"image"}' --file media=./demo.png --dry-run
  529. ```
  530. | Feature | Details |
  531. |---------|----------|
  532. | Dual-form auto-detection | Automatically selects api.dingtalk.com (header auth) or oapi.dingtalk.com (query-param auth) based on URL |
  533. | Automatic token management | App-level accessToken is fetched on first call, cached while valid, auto-refreshed on expiry |
  534. | Domain allowlist | Only `api.dingtalk.com` and `oapi.dingtalk.com` permitted — prevents token leakage |
  535. | Auto-pagination | `--page-all` iterates all pages. `--page-limit` caps the maximum (default 10, set to 0 for unlimited, hard cap at 500 to prevent infinite loops) |
  536. | Secure transport | HTTPS/443 and same-origin HTTPS redirects only; bounded JSON/error reads and streamed atomic binary downloads |
  537. | Agent discovery | When product commands do not cover an API, the bundled misc/mono Skill follows `https://open.dingtalk.com/llms.txt` to the official endpoint docs; raw `api` remains excluded from Agent Schema |
  538. `dws api` automatically uses only an internal-app App Token. It does not read OAuth User Tokens and does not expose `--as user` / `--user`. Prefer an existing DWS product command; use this escape hatch only for an uncovered internal-app server OpenAPI. Review a dry-run and confirm before create, update, delete, revoke, or send operations.
  539. </details>
  540. <details>
  541. <summary><strong>Smart Input Correction</strong> — auto-corrects common AI model parameter mistakes</summary>
  542. Built-in pipeline engine that normalizes flag names, splits sticky arguments, and fuzzy-matches typos:
  543. ```bash
  544. # Naming convention auto-conversion (camelCase / snake_case / UPPER -> kebab-case)
  545. dws aitable record query --baseId BASE_ID --tableId TABLE_ID # auto-corrected to --base-id --table-id
  546. # Sticky argument splitting
  547. dws contact user search --query "engineering" --timeout30 # auto-split to --timeout 30
  548. # Fuzzy flag name matching
  549. dws aitable record query --base-id BASE_ID --tabel-id TABLE_ID # --tabel-id -> --table-id
  550. # Value normalization (boolean / number / date / enum)
  551. # "yes" -> true, "1,000" -> 1000, "2024/03/29" -> "2024-03-29", "ACTIVE" -> "active"
  552. ```
  553. | Agent Output | dws Auto-Corrects To |
  554. |-----------|--------------|
  555. | `--userId` | `--user-id` |
  556. | `--limit100` | `--limit 100` |
  557. | `--tabel-id` | `--table-id` |
  558. | `--USER-ID` | `--user-id` |
  559. | `--user_name` | `--user-name` |
  560. </details>
  561. <details>
  562. <summary><strong>jq Filtering & Field Selection</strong> — fine-grained output control to reduce token consumption</summary>
  563. ```bash
  564. # Built-in jq expressions
  565. dws aitable record query --base-id BASE_ID --table-id TABLE_ID --jq '.invocation.params'
  566. dws schema "dev app create" --jq '.parameters'
  567. # Return only specific fields
  568. dws aitable record query --base-id BASE_ID --table-id TABLE_ID --fields invocation,response
  569. ```
  570. </details>
  571. <details>
  572. <summary><strong>Schema Introspection</strong> — Agent command discovery and execution contracts</summary>
  573. ```bash
  574. dws schema aitable --compact # discover product commands
  575. dws schema "aitable record query" --compact # view the selected Agent leaf contract
  576. dws schema "aitable record query" --jq '[.parameters | to_entries[] | select(.value.required)]' # view required fields
  577. dws schema --all # full export for CI/audit/baselines
  578. ```
  579. </details>
  580. <details>
  581. <summary><strong>Pipe & File Input</strong> — read flag values from files or stdin</summary>
  582. ```bash
  583. # Read message body from a file
  584. dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
  585. --title "Weekly Report" --text @report.md
  586. # Pipe content via stdin
  587. cat report.md | dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
  588. --title "Weekly Report"
  589. # Read from stdin explicitly
  590. dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
  591. --title "Weekly Report" --text @-
  592. ```
  593. > **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.
  594. </details>
  595. ## DingTalk bot — connect a robot to your local AI
  596. `dws dev connect` bridges a DingTalk robot to a local AI CLI (Claude Code / Codex / opencode / Qoder / Gemini / [Pi](docs/pi-agent.md), 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.
  597. ```bash
  598. dws dev connect --channel auto --unified-app-id <unifiedAppId>
  599. ```
  600. > `--unified-app-id` resolves `clientSecret` at runtime via `dev app credentials get`,
  601. > so the secret never appears in argv (`ps` / journald / shell history). The
  602. > legacy `--robot-client-id <id> --robot-client-secret <secret>` still works but
  603. > the CLI will warn you.
  604. In-chat **session commands** (send the bare command as the whole message — no agent turn, no tokens):
  605. | Command | Effect |
  606. |---------|--------|
  607. | `/new` (aliases `/start`, `/reset`) | Start a fresh session; the previous one is left intact (resumable where the agent supports it) |
  608. | `/clear` | Wipe the current session — disposed through the agent's real session op (opencode issues `DELETE /session/:id`); channels whose agent exposes no delete primitive fall back to a reset |
  609. See [`docs/robot-quickstart.md`](./docs/robot-quickstart.md) for the full 4-step walkthrough (install → create robot → connect → add to a group).
  610. ## Key Services
  611. | Service | Command | Capabilities |
  612. |---------|---------|--------------|
  613. | Contact | `contact` | Look up users, departments, labels, roster profiles and dismissals; create enterprises and enterprise accounts; invite employees |
  614. | Chat / IM | `chat` (`im`) | Send / reply / search messages, group & member management, bot & webhook messaging, reactions, recall |
  615. | Calendar | `calendar` | Events CRUD, attendees, meeting rooms, free/busy & time suggestions |
  616. | Todo | `todo` | Create / list / update / complete tasks and comments |
  617. | Approval | `oa` | Approve / reject / revoke / transfer; query pending / initiated / CC instances and forms |
  618. | Attendance | `attendance` | Clock-in records, shifts, summaries, group rules (read-only) |
  619. | Ding | `ding` | Send / recall DING messages |
  620. | Report | `report` | Create / submit logs, inbox & outbox, templates, statistics |
  621. | AI Tables | `aitable` | Bases / tables / records / fields / views, permissions & roles, automation, charts & dashboards, import / export |
  622. | Doc | `doc` | Search / read / write docs, block-level editing, comments, permissions, media, up / download |
  623. | Whiteboard | `whiteboard` | Standalone / embedded whiteboards: query, create / update, Diff, local SVG previews, personal / team templates |
  624. | Drive | `drive` | List / search / download, folders, upload, copy / move / rename, permissions |
  625. | Minutes | `minutes` | AI meeting notes: list, summary / keywords / transcription / todos, mind map, speakers, tags |
  626. | Mail | `mail` | Mailboxes, KQL search, read / send, drafts, folders, templates, contacts |
  627. | Sheet | `sheet` | Online spreadsheets: worksheet & range read / write, filters, conditional format, images, CSV |
  628. | Wiki | `wiki` | Knowledge bases: spaces, members, node tree, docs & files |
  629. | DevDoc | `devdoc` | Search the Open Platform docs and diagnose API errors |
  630. | AI Search | `aisearch` | Enterprise people search by name / dept / role / duty / supervisor / phone / job-number |
  631. | Live | `live` | List my live streams |
  632. | Raw API | `api` | Call App Token-capable server-side DingTalk OpenAPIs directly, with managed app-level token |
  633. > Full command listing with usage scenarios: [`docs/command-index.md`](./docs/command-index.md). Run `dws --help` for the top-level tree, or `dws <service> --help` for any service's subcommands.
  634. > **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.
  635. <details>
  636. <summary>Coming soon</summary>
  637. - `conference` (video meetings)
  638. - Multi-skill mode (default) — per-product skills under `skills/multi/`; installs and upgrades default to it, `dws skill setup --mode mono` switches back after interactive confirmation
  639. </details>
  640. <h2 id="security-by-design">Security by Design</h2>
  641. `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.
  642. <details>
  643. <summary><strong>For Developers</strong></summary>
  644. | Mechanism | Details |
  645. |-----------|----------|
  646. | **Encrypted token storage** | **PBKDF2 + AES-256-GCM** encryption, keyed by device physical MAC address; cross-platform Keychain/DPAPI integration provides additional protection — tokens cannot be decrypted on another machine |
  647. | **Input security** | Path traversal protection (symlink resolution + working directory containment), CRLF injection blocking, Unicode visual spoofing filtering — prevents AI Agents from being tricked by malicious instructions |
  648. | **Domain allowlist** | `DWS_TRUSTED_DOMAINS` defaults to `*.dingtalk.com`; bearer tokens are never sent to non-allowlisted domains |
  649. | **HTTPS enforced** | All requests require TLS; HTTP only permitted for loopback during development |
  650. | **Dry-run preview** | `--dry-run` shows call parameters without executing, preventing accidental mutations |
  651. | **Zero credential persistence** | Client ID / Secret used in memory only — never written to config files or logs |
  652. </details>
  653. <details>
  654. <summary><strong>For Enterprise Admins</strong></summary>
  655. | Mechanism | Details |
  656. |-----------|---------|
  657. | **OAuth device-flow auth** | Users must authenticate through an admin-authorized DingTalk application |
  658. | **Least-privilege scoping** | CLI can only invoke APIs granted to the application — no privilege escalation |
  659. | **Allowlist gating** | Admin confirmation required during co-creation phase; self-service approval planned |
  660. | **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 |
  661. </details>
  662. <details>
  663. <summary><strong>For ISVs</strong></summary>
  664. | Mechanism | Details |
  665. |-----------|---------|
  666. | **Tenant data isolation** | Operates under authorized app identity; cross-tenant access is impossible |
  667. | **Skill sandbox** | Agent Skills are Markdown documents (`SKILL.md`) — prompt descriptions only, no arbitrary code execution |
  668. | **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 |
  669. </details>
  670. > Found a vulnerability? Report via [GitHub Security Advisories](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/security/advisories/new). See [SECURITY.md](./SECURITY.md).
  671. ## Reference & Docs
  672. - [International DingTalk (`.io`) guide](./docs/international-region-guide.md) — international login, domestic/international profile switching, isolated testing, and troubleshooting
  673. - [Command Index](./docs/command-index.md) — every runtime command with description and when-to-use guidance
  674. - [Reference](./docs/reference.md) — environment variables, exit codes, output formats, shell completion
  675. - [Architecture](./docs/architecture.md) — static endpoint pipeline, command surface, transport layer
  676. - [Open Platform App Command Routing](./docs/dev-yulan-command-routing.md) — yulan dev app command design, MCP overlay, permission flow, and Agent routing
  677. - [Changelog](./CHANGELOG.md) — release history and migration notes
  678. ## Contributing
  679. See [CONTRIBUTING.md](./CONTRIBUTING.md) for build instructions, testing, and development workflow.
  680. ## License
  681. Apache-2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.