dingtalk-real-ai/dingtalk-workspace-cli

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. Join the DingTalk DWS co-creation group for support and updates. See Getting Started below.

---

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

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

OpenHarmony build

The repository supports an openharmony/arm64 build with a Go 1.26.7 OpenHarmony toolchain. Every beta and stable release builds, self-signs, verifies, and publishes dws-openharmony-arm64.tar.gz alongside the six platform archives, and the binary has been validated on a HarmonyOS PC.

OHOS_GO=/path/to/openharmony-go \
  DWS_PACKAGE_VERSION=1.2.3 \
  ./scripts/dev/build-openharmony.sh

# Or create a self-signed package archive (dws-openharmony-arm64.tar.gz):
OHOS_GO=/path/to/openharmony-go \
  DWS_PACKAGE_VERSION=1.2.3 \
  ./scripts/dev/package-openharmony.sh

The build is CGO_ENABLED=0 and therefore keeps SafeChat unavailable. Runtime native payloads are also unsupported on OpenHarmony. The script verifies the resulting static AArch64 ELF and its Go build metadata; see docs/openharmony.md for the complete boundary.

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

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

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

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

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 默认通过 npm Registry 查询发行版本。官方开源版独立二进制从同版本 GitHub Release 下载当前平台归档和技能包，校验后自更新，无需安装 npm；npm、pnpm 和 Homebrew 安装交由对应包管理器升级。详见版本来源与升级方式。

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

dws upgrade 默认选择正式渠道；--beta 选择 npm 的 beta 渠道。显式配置的 GitHub 升级来源仍使用原有协议。

auth status、version 和 --version 也会显示版本检查结果；未知命令或参数报错时，发现新版会提示升级。检查不会自动安装软件，详见版本检查与升级提示。

Six-channel post-release verification

Maintainers and release validators can run the release-quality smoke checks for curl, PowerShell, npm stable, npm beta, Homebrew, and dws upgrade:

git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git /tmp/dws-verify
cd /tmp/dws-verify/verify
bash verify-all-channels.sh

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 for the platform matrix.

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.

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 whiteboard +query --node "" --view summary --format json  # inspect a whiteboard
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 ""   # create a todo (replace )
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.

Whiteboards

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.

dws whiteboard --help
dws whiteboard render --source @whiteboard.json --output ./whiteboard-preview.svg --format json
dws whiteboard +diff --help
dws whiteboard template personal list --format json
dws whiteboard template team list --template-workspace "" --page-all --format json
dws whiteboard template public list --query "retrospective" --format json

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.

See the whiteboard reference, Diff guide, and SVG preview guide.

Using with Agents

dws is designed as an AI-native CLI. Complete Installation and Getting Started first, then install Agent Skills:

npx skills add DingTalk-Real-AI/dingtalk-workspace-cli -g

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 Invocation Patterns

# Use --yes to skip confirmation prompts (required for agents)
dws todo task create --title "Review PR" --executors "" --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

Use Cobra help and Schema for different parts of the command contract:

• dws --help is the source of truth for whether a command exists and which flags the binary accepts.
• dws schema "" --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.
• If Help and Schema disagree, treat it as contract drift: pass only flags accepted by Cobra and use the more conservative safety semantics.
• Schema describes commands; it does not read or search DingTalk business data. Execute the real product command after discovery.

# Confirm that the command exists and inspect accepted flags
dws aitable record query --help

# Discover within a product, then inspect the selected leaf contract
dws schema aitable --compact
dws schema "aitable record query" --compact

# Execute the real business query
dws aitable record query --base-id BASE_ID --table-id TABLE_ID --limit 10

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.

Agent Skills

npx skills add DingTalk-Real-AI/dingtalk-workspace-cli -g

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

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.

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.

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.

The repo ships two source trees:

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

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.

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

China users: npx skills add clones from GitHub. Prefer dws skill setup or prefix DWS_GITEE_REPO on install-skills.sh — see China mirror.

Power-user / China / upgrade: dws skill setup

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

# Preview the exact directories that mono setup would back up and replace
dws skill setup --mode mono --target all --dry-run

# Run interactively and confirm the listed directories
dws skill setup --mode mono --target all

# Preview, then install multi skills to a single agent home with interactive confirmation
dws skill setup --mode multi --target cursor --dry-run
dws skill setup --mode multi --target cursor

# Point at a local source (an extracted dws-skills.zip root, its multi/ directory, or a source checkout), preview first
DWS_SKILL_SOURCE=/absolute/path/to/extracted-dws-skills dws skill setup --mode multi --dry-run
DWS_SKILL_SOURCE=/absolute/path/to/extracted-dws-skills dws skill setup --mode multi

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//; 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.

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.

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

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

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 / Pi, 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 

--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 --robot-client-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 --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.

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.

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

Reference & Docs

• International DingTalk (.io) guide — international login, domestic/international profile switching, isolated testing, and troubleshooting
• 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