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

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

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.

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.

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

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

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.

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

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

Flag	Description
--check	Check for updates without installing
--list	List available stable release versions with changelogs
--beta	Use the beta pre-release track for upgrade, --check, or --list
--version	Upgrade to a specific version (e.g. v1.0.7 or v1.0.8-beta.1)
--rollback	Rollback to the previous backed-up version
--force	Force reinstall even if already on the latest version
--skip-skills	Skip skill package update
-y	Skip confirmation prompt

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