Calicat Cli Operator

Calicat CLI Design Data

Use this skill when the user wants data from a Calicat file and the local calicat CLI is the execution path.

Read This File For

• skill trigger conditions
• link-form detection
• progressive retrieval rules
• task routing by user intent

Read Extra References Only When Needed

• If the task depends on making sure the CLI is installed, checking its version, updating it, or telling another agent/user how to install/update it, read references/cli-lifecycle.md.

Link Parsing

Calicat design links commonly appear in three forms.

File only

https://www.calicat.cn/design/2066708151519244288

Parse as:

• file_id = 2066708151519244288
• canvas_id = unknown
• selected_layer_id = unknown

Meaning:

• The user identified the file, but not a specific canvas or layer.
• If the task is canvas-specific, call get_canvas_list first.

Canvas link

https://www.calicat.cn/design/2066708151519244288?node-id=2066708151531827200&node-type=canvas

Parse as:

• file_id = 2066708151519244288
• canvas_id = 2066708151531827200
• selected_layer_id = unknown

Meaning:

• Here node-id is the canvas id.
• Do not send this node-id to get_meta_data or get_design_data as if it were a layer id.
• For canvas-wide work, go straight to get_design_page_list with that canvas_id.

Layer link

https://www.calicat.cn/design/2066708151519244288?node-id=21c84811-08c9-42f6-9dc7-82c6992a6ae8&node-type=group

Parse as:

• file_id = 2066708151519244288
• selected_layer_id = 21c84811-08c9-42f6-9dc7-82c6992a6ae8
• canvas_id = unknown

Meaning:

• Here node-id is a layer id.
• node-type=group is a strong hint that this is a layer-like object, not a canvas.
• Start with get_meta_data, then decide whether to read full design data.

Parsing Rules

• Always extract file_id from /design/{file_id} first.
• If node-type=canvas, treat node-id as canvas_id.
• If node-type exists and is not canvas, treat node-id as selected_layer_id.
• If node-id exists but node-type is missing, do not guess immediately:
• if the id looks like a UUID, it is usually a layer id
• if the id is a long numeric string, it may be a canvas id
• but when the next step matters, verify by choosing the lightest safe API path

Safe Resolution Strategy

When the link is ambiguous:

• Parse file_id.
• Inspect node-type.
• If still ambiguous, prefer canvas discovery before large reads.
• Do not force a layer workflow on a probable canvas link.

Core Rule

Prefer progressive retrieval.

Large get_design_data payloads can easily blow up context. Start with the lightest structure endpoint that answers the next decision:

• get_canvas_list
• get_design_page_list
• get_meta_data
• get_design_data
• get_interaction_design_data

Treat this as directory first, full content later.

API Selection: get_meta_data vs. get_design_data

• get_meta_data: Retrieves simplified page/layer structure (layer names, IDs, positions, dimensions) with the hierarchy represented in XML format. Use this to quickly inspect layer outlines, map out canvas structures, or locate specific nested elements without loading heavy style payloads.
• get_design_data: Retrieves the complete layout and deep CSS/styling values. Use this to generate precise code or perform styling analysis.
• Direct Fetch Rule: If the target page layer ID is already determined (e.g. from get_design_page_list) and your goal is frontend code implementation for that page, do not call get_meta_data first. Call get_design_data directly on the page ID.

Payload Storage & Context Management

Large payloads from get_design_data can easily overwhelm the LLM's context window. Directly outputting massive JSON payloads to the terminal pollutes the context, causing slow responses, high token costs, and potential token overflow.

To keep the LLM context clean and performance optimal:

• Redirect Output to File: Always redirect large output payloads to a temporary file within the workspace (e.g., scratch/page_design.json or temp_design.json).
• Unix Bash/Zsh:

    calicat tools-call --name get_design_data --args '{"file_id":"123","selected_layer_id":"xyz"}' > scratch/page_design.json

• PowerShell:

    $json = '{\"file_id\":\"123\",\"selected_layer_id\":\"xyz\"}'
    calicat tools-call --name get_design_data --args $json > scratch/page_design.json

• Strict Data-Driven Implementation (No Guessing or Hallucinations):
• Do not start implementing full frontend code based on incomplete design data or placeholders. Coding must strictly correspond to the actual page design data and user requirements. Guessing leads to design-code mismatches.
• Implement design layouts page-by-page. A single page's design_data is typically small enough to not overflow the context. Alternatively, locate the target modular component/container, extract its specific node data first, and develop that segment.
• Handling Giant JSON Files (Splitting to Prevent Harness Truncation):
• If the output file is extremely large, do not attempt to read or display the entire file in a single turn. Reading huge files directly will trigger the agent harness truncation.
• Write a simple parsing script (e.g., in Python or NodeJS) to split the giant JSON file into smaller, logical files (e.g., by single component, screen section, or layout tree depth) saved under scratch/.
• Process and build code from these smaller split JSON files one by one.
• Progressive and Targeted Reading: Once saved, do not read the entire file into the context at once. Use standard workspace file-viewing tools with line limits (e.g., view_file with specific range offsets), or write a small script (e.g., Python/JS) to parse and filter the JSON down to the specific UI node details required for coding.

Minimal CLI Surface

List tools:

calicat tools-list

Windows Shell JSON Argument Escaping

If the execution environment is Windows (PowerShell or CMD), passing raw JSON objects inside single quotes can lead to argument parsing issues (such as quotes being stripped). Follow these escaping rules:

• PowerShell: Declare the JSON string in a variable, escape internal double quotes with a backslash (\), and pass the variable.

  $json = '{\"file_id\":\"2045068433773035520\",\"selected_layer_id\":\"e449643f-0bc3-4b75-9fa4-9db5c0b0e402\"}'
  calicat tools-call --name get_meta_data --args $json

• CMD: Wrap the entire arguments object in double quotes and escape internal double quotes with a backslash (\").

  calicat tools-call --name get_meta_data --args "{\"file_id\":\"2045068433773035520\",\"selected_layer_id\":\"e449643f-0bc3-4b75-9fa4-9db5c0b0e402\"}"

CLI Command Examples (Unix-like Bash/Zsh)

Canvas list:

calicat tools-call --name get_canvas_list --args '{"file_id":"123456"}'

Page list:

calicat tools-call --name get_design_page_list --args '{"file_id":"123456","canvas_id":"canvas-id"}'

Layer meta:

calicat tools-call --name get_meta_data --args '{"file_id":"123456","selected_layer_id":"layer-uuid"}'

Layer design data:

calicat tools-call --name get_design_data --args '{"file_id":"123456","selected_layer_id":"layer-uuid"}'

Interaction design:

calicat tools-call --name get_interaction_design_data --args '{"file_id":"123456","selected_layer_id":"layer-uuid"}'

PRD list:

calicat tools-call --name get_prd_list --args '{"file_id":"123456"}'

PRD full content:

calicat tools-call --name get_prd_full_content --args '{"file_id":"123456","prd_id":"prd-id"}'

Recommended Workflow By Task

Single layer design analysis

Use when the user gives a design URL and asks for one layer's design or interaction data.

Workflow:

• Parse the link shape first.
• Confirm that the link actually points to a layer, not a canvas.
• Call get_meta_data.
• Confirm the layer looks like the target.
• Call get_design_data.
• If interaction matters, call get_interaction_design_data.

Canvas-level work

Use when the user asks for “这个画布”, “当前画布”, or asks to process all pages inside a canvas.

Workflow:

• Parse the link shape first.
• If the URL contains node-id and node-type=canvas, treat node-id as canvas_id.
• If the URL does not contain node-id (e.g., file-only link) or node-id is ambiguous:
• Call get_canvas_list to fetch the list of all canvases for the file.
• Determine the target canvas_id from the list (ask the user to select, or infer based on context/defaults).
• Call get_design_page_list using the resolved canvas_id to fetch the list of pages.
• Process one page layer at a time.
• For each page:
• If the goal is frontend code implementation, directly call get_design_data using the page ID (skip get_meta_data). Always redirect the output to a temporary JSON file to avoid polluting the prompt context.
• Otherwise, call get_meta_data first if you only need to inspect page skeletal outlines or locate specific component layers before deciding what to fetch.

Requirement card retrieval

Use when the user asks for requirements, PRDs, summaries, or requirement card content.

Workflow:

• Parse file_id.
• Call get_prd_list.
• Match by title or summary.
• Call get_prd_full_content.

Never guess prd_id first.

Full canvas frontend implementation

Use when the user asks to build frontend code for “all designs”, “all pages”, or “the whole canvas”.

Workflow:

• Resolve file_id.
• Resolve canvas_id (if the URL does not contain node-id, call get_canvas_list first to list all canvases and select the target).
• Call get_design_page_list using the resolved canvas_id to fetch the list of pages.
• Process one page layer at a time.
• For each page, directly call get_design_data (always redirect the output to a temporary JSON file to avoid polluting the prompt context) to get the complete styling details, and then implement/summarize the code. Skip get_meta_data.
• Move to the next page only after finishing the current one.

Do not fetch all page design data in a single pass.

Default batch size:

• 1 page per step
• 2 pages only if payloads are clearly small

Decision Heuristics

If the user says:

• “这个链接里的图层”

use the layer path

• “这个链接里的画布”

use the canvas path

• “这个文件里的 PRD”

use file_id, then get_prd_list

• “这个画布里的所有页面”

resolve canvas_id, then get_design_page_list

• “把整个设计做成前端”

do not pull everything at once; page-by-page retrieval is mandatory

Failure Handling

If data access fails:

• Run calicat status.
• If auth looks stale, run calicat logout then calicat login.
• Re-check parsed file_id, canvas_id, and node-id.
• If the task depends on install/update/version state, read references/cli-lifecycle.md.

Output Style

When reporting back to the user:

• explicitly say which ids you parsed
• explicitly say which CLI calls you made
• explicitly say whether the link pointed to a file, canvas, or layer
• if you use progressive retrieval, explain that you are avoiding loading huge design JSON all at once

CLI Lifecycle

Read this file only when the task depends on local CLI availability, version, install, or update.

Version Check

Check current CLI version:

calicat -V

Check whether a new version exists:

calicat update --check

Interpretation:

• if hasUpdate is false, continue with the current CLI
• if hasUpdate is true, prefer updating before debugging strange CLI behavior

Update

Preferred update command:

calicat update

This uses the official installer path behind the scenes.

The CLI may also print a reminder during common commands like:

• calicat login
• calicat status
• calicat tools-list
• calicat tools-call

The reminder is informational. It does not silently auto-upgrade.

Install

If the user does not have calicat installed, guide them by platform.

macOS / Linux

curl -fsSL https://www.calicat.cn/cli/install.sh | bash

Windows PowerShell

powershell -ExecutionPolicy Bypass -c "irm https://www.calicat.cn/cli/install.ps1 | iex"

After install, verify:

calicat --help
calicat -V

Uninstall

macOS / Linux

rm -f ~/.local/bin/calicat
rm -rf ~/.calicat-cli

Windows PowerShell

Remove-Item "$HOME\\.calicat-cli" -Recurse -Force
Remove-Item "$HOME\\.calicat-cli\\bin\\calicat.exe" -Force -ErrorAction SilentlyContinue

If the user only wants to clear auth state:

calicat logout

Minimal Troubleshooting

If calicat exists but behaves unexpectedly:

1. check calicat -V 2. run calicat update --check 3. if a newer version exists, update first 4. run calicat status 5. if auth is stale, run calicat logout then calicat login