lark-whiteboard-cli

[!NOTE] Environment Dependencies: Drawing on the whiteboard requires

@larksuite/whiteboard-cli

(Whiteboard Node.js CLI tool) and

lark-cli

(LarkSuite CLI tool). If execution fails, install manually and try again:

npm install -g @larksuite/whiteboard-cli@^0.2.0

[!IMPORTANT] Be sure to get user consent before executing

npm install

to install new dependencies!

Workflow

This is a whiteboard, not a web page. Elements are placed freely on an infinite canvas, and flex layout is an optional enhancement.

Step 1: Routing & Knowledge Reading
  - Determine the rendering path (see routing table): Mermaid or DSL?
  - Read the corresponding scene guide — understand structural features and layout strategies
  - Determine the layout strategy (see quick judgment below) and construction method
  - Read references/ core modules — syntax, layout, color matching, typography, connectors

Step 2: Generate complete DSL (including colors)
  - Plan information volume and grouping according to content.md
  - Select layout mode and spacing according to layout.md
  - It is recommended to use icons to make the chart more intuitive, run `npx -y @larksuite/whiteboard-cli@^0.2.0 --icons` to view available icons and select appropriate ones. Do not overuse icons or use them for all charts, choose whether to use icons according to chart type and content
  - Color according to style.md (use the default classic color palette if not specified by the user)
  - Output complete JSON according to schema.md syntax
  - Refer to connectors.md for connections, refer to typography.md for typesetting

  Note: For some graphics (fishbone, flywheel, bar chart, line chart, etc.), you need to write a .js script according to the script template in the scene guide to generate JSON:
    1. Create output directory ./diagrams/YYYY-MM-DDTHHMMSS/
    2. Save the script as diagram.gen.js, execute node diagram.gen.js to generate diagram.json
    3. Use the generated diagram.json to enter Step 3

Step 3: Render & Review → Deliver
  - Self-check before rendering (see checklist below)
  - Render PNG, check:
    · Is the information complete? Is the layout reasonable? Is the color matching coordinated?
    · Is there no text truncation? No crossing connections?
  - If there are problems → fix according to the symptom table → re-render (up to 2 rounds)
  - If there are still serious problems after 2 rounds → consider using the Mermaid path as a fallback
  - If no problem → deliver:
    · User requests upload to LarkSuite Whiteboard → see the description in the "Upload to LarkSuite Whiteboard" section below
    · User does not specify → show PNG image to user

references/layout.md

references/layout.md

The construction method is a strong constraint: When the scene guide requires "script generation", you must first write the script (.js) and execute it with

node

to generate the JSON file. The coordinates of absolute positioning scenarios (fishbone diagram, flywheel diagram, bar chart, line chart, etc.) require mathematical calculation, and directly writing JSON by hand can easily lead to node overlap or connection penetration.

Rendering Path Selection (DSL or Mermaid)

1. Automatic Mermaid: Mind maps, sequence diagrams, class diagrams, pie charts → use Mermaid by default
2. Explicit Mermaid: User input contains Mermaid syntax → use Mermaid
3. DSL Path: All other types → read core modules first, then read the corresponding scene guide

scenes/mermaid.md

.mmd

Module Index

Core References (Required for DSL Path)

references/schema.md

references/content.md

references/layout.md

references/typography.md

references/connectors.md

references/style.md

Scene Guides (Select one according to type)

scenes/architecture.md

scenes/organization.md

scenes/swimlane.md

scenes/comparison.md

scenes/fishbone.md

scenes/bar-chart.md

scenes/line-chart.md

scenes/treemap.md

scenes/funnel.md

scenes/pyramid.md

scenes/flywheel.md

scenes/milestone.md

scenes/flowchart.md

scenes/mermaid.md

File Output Specification

./diagrams/

YYYY-MM-DDTHHMMSS

./diagrams/
  2026-03-27T143000/      ← Automatically created by time, no need to name
    diagram.json          ← DSL (CLI input)
    diagram.gen.js        ← Coordinate calculation script (only for script construction method)
    diagram.png           ← Final image
    diagram.mmd           ← Mermaid source code (only for Mermaid path)

CLI Commands

npx -y @larksuite/whiteboard-cli@^0.2.0 --icons

npx -y @larksuite/whiteboard-cli@^0.2.0 -i ./diagrams/2026-03-27T143000/diagram.json -o ./diagrams/2026-03-27T143000/diagram.png    # DSL
npx -y @larksuite/whiteboard-cli@^0.2.0 -i ./diagrams/2026-03-27T143000/diagram.mmd -o ./diagrams/2026-03-27T143000/diagram.png     # Mermaid

Upload requires LarkSuite authentication. When encountering authentication or permission errors, read

../lark-shared/SKILL.md

to learn about login and permission handling.

XXX

lark-cli docs +fetch --doc <URL> --as user

<whiteboard token=”XXX”/>

lark-cli docs +update --doc <doc_id> --mode append --markdown '<whiteboard type=”blank”></whiteboard>' --as user

data.board_tokens[0]

../lark-doc/SKILL.md

[!CAUTION] MANDATORY PRE-FLIGHT CHECK When you want to write content to an existing whiteboard Token, it is absolutely forbidden to execute the upload command directly! You must strictly follow the two steps below: Mandatory Dry Run (status detection) You must first add the

--overwrite --dry-run

parameter to the command to detect the current status of the whiteboard. Example command:

bash

npx -y @larksuite/whiteboard-cli@^0.2.0 --to openapi -i <input file> --format json | lark-cli whiteboard +update --whiteboard-token <Token> --source - --overwrite --dry-run --as user

Parse results and intercept

• Read the output log of Dry Run carefully.
• If the log contains

  XX whiteboard nodes will be deleted

  : This means the whiteboard is not empty, and the current operation will overwrite and destroy the user's original chart!
• You must stop the operation immediately, and confirm with the user through the

  AskUserQuestion

  tool (or direct reply): "The target whiteboard is not empty currently, continuing the update will clear the original XX nodes, do you confirm to overwrite?"
• Only after the user explicitly authorizes "agree to overwrite" can you remove

  --dry-run

  and actually perform the upload.
• The user may ask you not to overwrite and update the whiteboard content, in this case, remove the

  --overwrite

  and

  --dry-run

  parameters before uploading.

npx -y @larksuite/whiteboard-cli@^0.2.0 --to openapi -i <input file> --format json | lark-cli whiteboard +update --whiteboard-token <Whiteboard Token> --source - --yes --as user

The whiteboard cannot be modified once uploaded. If you need to upload as an application identity, replace

--as user

with

--as bot

. If the whiteboard is not empty, first add

--overwrite --dry-run

to check the number of nodes to be deleted, and remove

--dry-run

to execute after confirming with the user.

Pre-rendering Self-check

• Different groups use different colors? Nodes in the same group have exactly the same style?
• Light background for outer layer, white nodes for inner layer? (Heavy outside, light inside)
• All nodes have borders (borderWidth=2)? Text is clearly readable on the background?
• Connections use gray (#BBBFC4), no color?
• All frames have layout attribute set? gap and padding are explicitly set?
• Nodes containing text use fit-content for height? connector is in the top-level nodes array?

Key Constraints Quick Check

The most frequently error-prone rules that must be followed even if you do not read the sub-module files.

1. The height of nodes containing text must use

   'fit-content'

   — fixed values will truncate text

2. fill-container

   only takes effect in flex parent containers — width degenerates to 0 under

   layout: 'none'

3. Containers with

   layout: 'none'

   must have fixed width and height — do not use

   fit-content

4. connector must be placed in the top-level nodes array — cannot be nested in frame children
5. Layer order — array order = drawing order. Elements defined later have higher layers and will overwrite those defined first. Overlay/floating/annotation elements must be placed at the end of the array.
6. x/y in flex containers will be completely ignored — use

   layout: 'none'

   or place in top-level nodes when free positioning is required
7. Dagre sub-containers are opaque nodes by default — outer connections cannot address their internal child nodes (the engine will automatically redirect to the shell). When penetration is required, declare

   layout: "dagre"

   +

   layoutOptions: { isCluster: true }

{ "type": "frame", "layout": "vertical", "children": [
  { "type": "rect", "x": 100, "y": 0, "text": "成都" },
  { "type": "rect", "x": 540, "y": 0, "text": "康定" }
]}

layout: "none"

layout: "none"

width: "fit-content", height: "fit-content"