DOCSEARCHbyAlgolia
Submit Docs

DingTalk Workspace CLI (dws)

repository·main·Indexed 25 days ago

https://github.com/dingtalk-real-ai/dingtalk-workspace-cli

A command-line tool for human users and AI agents to interact with DingTalk enterprise data. It features a zero-trust architecture, structured JSON outputs, and built-in Agent Skills. The CLI provides access to contacts, calendar, docs, minutes, drive, and todo tasks, and supports multiple authentication profiles and custom app modes for CI/CD or ISV integration.

Tokens
279.3K
Snippets
478
Records
1.3K
Agent score
80%

What's inside dingtalk-workspace-cli

  1. Overview of DingTalk Mail (dws mail) commands

    main

    The dws mail command suite provides comprehensive management for DingTalk email services, including mailbox management, message operations, folder/tag organization, user searching, and automation settings.

    Key functional areas include:

    • Mailbox & Profile: List your own mailboxes and view detailed profiles (capacity, aliases).
    • Messages: List, search (via KQL), get content, send, reply, forward, and batch operations (move, delete, update status).
    • Folders & Tags: Create, list, update, and delete folders and tags.
    • Attachments: List and download attachments (note: downloads must be performed one by one).
    • Threads: Manage email conversation threads and their statuses.
    • User Search: Search the address book to find other users' email addresses (distinct from searching for emails).
    • Templates & Contacts: Manage email templates and personal email contacts.
    • Automation & Rules: Configure auto-replies, allow-lists, block-lists, and receiving rules.

  2. Overview of the `dws dev` command group

    main

    The dws dev command group is designed for developers to manage the lifecycle of DingTalk Open Platform applications and robots. It is divided into three main sub-trees:

    • dev app: Manages the application lifecycle, including creation, querying, updating, deleting, credentials, permissions, members, security, web pages, robots (including account creation), versions, and event subscriptions.
    • dev connect: Used for connection (建联). It connects an existing robot to the current local agent by starting a Stream. It does not create a new robot account.
    • dev doc: An entry point for searching DingTalk Open Platform development documentation.

    Important Distinction:

    • Use dws chat bot search/find only to query existing robots from an IM perspective.
    • Use dws dev app robot submit to create/register a new robot.
    • Use dws dev connect to connect a robot to a local agent.
    • Never use chat commands for creating or connecting robots.

  3. Overview of DingTalk Workspace CLI (dws) services

    main

    The dws CLI provides access to a wide range of DingTalk services. Each service is mapped to a top-level command. Use dws --help to see the full command tree or dws <service> --help to explore subcommands for a specific service.

    Key Services and Commands:

    ServiceCommandCapabilities
    ContactcontactLook up users, departments, labels, roster profiles and dismissals; create enterprises and enterprise accounts; invite employees
    Chat / IMchat (im)Send / reply / search messages, group & member management, bot & webhook messaging, reactions, recall
    CalendarcalendarEvents CRUD, attendees, meeting rooms, free/busy & time suggestions
    TodotodoCreate / list / update / complete tasks and comments
    ApprovaloaApprove / reject / revoke / transfer; query pending / initiated / CC instances and forms
    AttendanceattendanceClock-in records, shifts, summaries, group rules (read-only)
    DingdingSend / recall DING messages
    ReportreportCreate / submit logs, inbox & outbox, templates, statistics
    AI TablesaitableBases / tables / records / fields / views, permissions & roles, automation, charts & dashboards, import / export
    DocdocSearch / read / write docs, block-level editing, comments, permissions, media, up / download
    DrivedriveList / search / download, folders, upload, copy / move / rename, permissions
    MinutesminutesAI meeting notes: list, summary / keywords / transcription / todos, mind map, speakers, tags
    MailmailMailboxes, KQL search, read / send, drafts, folders, templates, contacts
    SheetsheetOnline spreadsheets: worksheet & range read / write, filters, conditional format, images, CSV
    WikiwikiKnowledge bases: spaces, members, node tree, docs & files
    DevDocdevdocSearch the Open Platform docs and diagnose API errors
    AI SearchaisearchEnterprise people search by name / dept / role / duty / supervisor / phone / job-number
    LiveliveList my live streams
    Raw APIapiCall any DingTalk OpenAPI directly, with managed app-level token

  4. Manage DingTalk profiles and multi-organization access

    main

    The dingtalk-profile skill allows managing multiple DingTalk accounts and switching between different organizations. A profile is defined as a unique corpId + userId identity. The current profile determines which identity is injected into a command.

    Note: This is an EXPERIMENTAL feature. For production or shared environments, it is recommended to use mono mode via dws skill setup --mode mono.

  5. Manage AITable automated workflows with dws

    main

    The dws aitable workflow command suite allows you to create, update, list, get, enable, and disable automated workflows (the "When X happens, automatically do Y" logic) within an AITable Base.

    Core Workflow Commands:

    • workflow create: Create and publish a new workflow.
    • workflow update: Update and publish an existing workflow.
    • workflow list: List all workflows in a Base (includes status, creator, and timestamps).
    • workflow get: Retrieve full details of a single workflow, including its flowSchema (the node DAG).
    • workflow enable: Enable a workflow to start running based on its triggers.
    • workflow disable: Disable a workflow (high risk; requires --yes for confirmation).

    Important Note: All subcommands require the --base-id flag (can also use the alias --base).

  6. Manage DingTalk AI Table Automations (Workflows)

    main

    The workflow command group allows you to create, update, list, retrieve, enable, and disable automated workflows (e.g., "When X happens, do Y") within a DingTalk AI Table Base.

    Core Workflow Lifecycle:

    1. Create/Update: Submit a workflow-dsl/v1 JSON object to define the logic.
    2. Verify: A successful command must return status=success, data.valid=true, and data.issues=[].
    3. Control: Use enable or disable to change the execution state.
    4. Monitor: Use list to check the current status (RUNNING or STOP).

    Important Constraints:

    • Deletion/Logs: Deleting workflows and viewing execution logs/history are currently not supported.
    • ID Naming: In workflow list output, the identifier is flowId. In enable/disable commands, it is referred to as workflowId. These are the same value.
    • Non-Idempotency: workflow create is not idempotent. If a network error occurs, use workflow list to check if the workflow was actually created before retrying.

  7. Use the dingtalk-markdown skill

    main

    The dingtalk-markdown skill is used for interacting with native DingTalk Markdown files. It is specifically designed for tasks like reading/downloading .md source files, creating new .md files, overwriting remote Markdown files, or performing partial text/regex replacements.

    Note: This skill is currently in EXPERIMENTAL mode. For production or shared environments, it is recommended to use mono mode via dws skill setup --mode mono.

    Command Prefix: dws markdown Required CLI Version: >=0.2.14 Prerequisites: The dws binary must be on your PATH. You should also refer to the dws-shared skill for authentication and global safety rules.

  8. Use the dingtalk-hrbrain skill for HR and talent management

    main

    The dingtalk-hrbrain skill is used for interacting with DingTalk's Hrbrain (Organizational Brain). It is specifically designed for queries related to talent pools, employee profiles, career history, performance records, and employee tags.

    Note: This skill is currently in EXPERIMENTAL mode. For production or shared environments, it is recommended to use mono mode via dws skill setup --mode mono.

    Command Prefix: dws hrbrain

    Prerequisites:

    • The dws binary must be on your PATH.
    • Ensure you have reviewed the dws-shared skill documentation for authentication and global flags.
    • Verify command availability using dws hrbrain <command> --help or test with --dry-run before actual execution.

  9. AI表格 (aitable) Command Reference Overview

    main

    The aitable command set provides a comprehensive interface for managing AI Tables (AI表格). This file serves as a routing index for commands. For detailed parameters, examples, and troubleshooting, refer to the specific sub-directories under aitable/ based on the command category.

    Command Categories:

    • base: Base management
    • table: Data table management
    • field: Field management (see aitable-field.md and field-properties for details)
    • record: Record management
    • view: View management
    • form: Form management (see aitable-form.md)
    • workflow: Automated workflows (see aitable-workflow.md)
    • dashboard & chart: Dashboard and chart management (see aitable-dashboard-chart.md)
    • export & import: Data export and import (see aitable-export-import.md)

  11. Perform fine-grained document editing with doc block commands

    main

    The dws doc block command suite allows for granular manipulation of document elements (blocks) such as paragraphs, headings, tables, and columns. You can perform four primary operations:

    1. List: Query existing block elements to retrieve their structure or specific UUIDs.
    2. Insert: Add new elements at specific locations (e.g., before, after, or at a specific --index within a parent container).
    3. Update: Modify the content or properties of an existing block using its --block-id.
    4. Delete: Remove a block from the document.

    There are two content formats available:

    • --content-format element: An older, secondary format using a specific JSON structure for elements.
    • --content-format jsonml: The preferred format for modern document manipulation, providing more precise control over the document tree structure.