wps

Kingsoft Docs CLI Skill User Guide

Kingsoft Docs CLI Skill provides a complete set of online document operation tools, interacting with the Kingsoft Docs API through the kdocs-cli command-line tool. It supports creating, querying, reading, editing, sharing, and moving multiple types of online documents.

Strict Rules

NEVER

NEVER allow the Token to appear in plaintext in conversations, logs, command output, code comments, or any file; the Token may only be saved to the system keychain via kdocs-cli auth set-token or kdocs-cli auth login Save to system keychain
Interfaces such as upload and write require passing in a content_base64 that may be very large (over 1 MB after encoding). NEVER generate the Base64 string token by token in the conversation; use a script to read the file, encode it, and pass the parameter

MUST

Before executing irreversible operations (delete/close type), confirmation must be obtained from the user
After a write operation is completed, an independent read request must be used to verify the actual result (do not trust code: 0）
After creating a document and verifying it passes, you must call get_file_link to get the link and show it to the user
Temporary JSON files created via --file or scripts (such as payload.json、temp.json) must be deleted after the entire operation process ends, to avoid leaving residue in the user's working directory

Keep the latest version

When to trigger:First use Skill / More than 24h since the last self-check / Received unknown action or unknown service error。

CLI version：kdocs-cli version — if the command does not exist, install it according to "Tool Installation and Authentication" below; if it is lower than the frontmatter versionin this file, run kdocs-cli upgrade -y(automatically backs up the old version; on failure you can kdocs-cli upgrade --rollback）
Skill version: if this file's version is lower than kdocs-cli version, run kdocs-cli call check_skill_update version=<本文件version>, if it returns update_available: true, extract the zip download link from instruction (format https://...kdocs.zip), download, extract, and replace the current Skill directory

If both upgrade and rollback fail, rerun the installation script in this Skill directory (bash setup.sh / powershell setup.ps1 / node setup.cjs, the script is located at scripts/) to reinstall from the CDN. If it still cannot be updated, rely on the toolset actually supported by kdocs-cli --help .

Tool Installation and Authentication

Operation	Command
Install	`bash scripts/setup.sh` / `powershell scripts/setup.ps1` / `node scripts/setup.cjs`
Authenticate	User has provided Token: `kdocs-cli auth set-token "<token>"` · No Token: `kdocs-cli auth login`

For the manual acquisition process when login fails,auth status diagnosis,auth logout logout, etc., see references/auth.md。

Invocation Format

kdocs-cli [parameters]

Parameter Passing

Parameter characteristics	Recommended method	Example
Simple value (no Chinese)	key=value	`kdocs-cli drive search-files keyword=test type=all`
Array/object, short JSON	JSON string	`kdocs-cli sheet query-records '{"file_id":"xxx","filter":{}}'`
Array/object, or contains Chinese/newlines/>200 characters	--file	`kdocs-cli otl insert-content --file payload.json`
Script pipeline integration	stdin	`node gen.js \| kdocs-cli otl insert-content -`

--file / stdin input must be that tool'sFull JSON parameter object
Chinese/multiline parametersProhibited key=value (Windows/PowerShell corrupts UTF-8 encoding)
Generate JSON files with Node.js/Python;Prohibited ConvertTo-Json (output includes BOM)
PowerShell must escape JSON strings with backslashes:'{\"key\":[\"val\"]}'

--file example: when writing large amounts of content, use a script to generate a JSON file and then --file pass it in; delete the temporary file after the operation is complete:
const fs = require('fs');
fs.writeFileSync('payload.json', JSON.stringify({
  file_id: "<file_id>",
  content: fs.readFileSync('article.md', 'utf8'),
  format: "markdown",
  mode: "append"
}), 'utf8');
kdocs-cli otl insert-content --file payload.json --silent
// 操作完成后清理临时文件
fs.unlinkSync('payload.json');

Global options：

Option	Description
`--token <token>`	One-time Token (highest priority, not persisted)
`--endpoint <url>`	Override default endpoint
`--compact`	Output compact JSON
`--silent`	Output only the `data` field
`--verbose`	Output request details to stderr
`--timeout <ms>`	HTTP request timeout (milliseconds, default 30000)

Help：kdocs-cli --help、kdocs-cli <service> --help、kdocs-cli <service> <action> --help

The following tools are irreversible; you must confirm with the user before invoking them (for detailed constraints, see the "Operation Constraints" section in each tool's reference documentation):

otl.block_delete、dbsheet.delete_sheet、kwiki.close_knowledge_view、sheet.delete_sheets、sheet.delete_range、dbsheet.delete_view、dbsheet.delete_fields、cancel_share、kwiki.delete_item、sheet.delete_protection_ranges、dbsheet.delete_records、sheet.delete_data_validations、sheet.delete_conditional_format_rules、sheet.delete_float_images、sheet.delete_filters、dbsheet.sheet_batch_delete、dbsheet.permission_delete_roles_async

Capability scope

Supported document types

Type	Alias	File extension	Description	Detailed reference
Smart document preferred	ap	.otl	Beautiful layout, supports rich components	`references/otl.md` — operations on pages, text, headings, to-dos, and other elements
Table	et / Excel	.xlsx	Dedicated to data tables	`references/sheet.md` — worksheet management, range data retrieval, batch updates
PDF document	pdf	.pdf	Dedicated to PDF documents	`references/pdf.md` — PDF creation and content reading
Word document	wps / Word	.docx	Traditional format	`references/wps.md` — Word document creation and content operations
Presentation	wpp	.pptx	Dedicated to PPT documents	`references/wpp.md` — slide theme font and color scheme settings, download and export
Smart table	as	.ksheet	Structured table, supports multiple views and field management	`references/sheet.md` — worksheet management, range data retrieval, batch updates
Multi-dimensional table	db / dbsheet	.dbt	Multiple data tables, rich field types and views (table/kanban/gantt, etc.)	`references/dbsheet.md` — supports full CRUD for data tables/views/fields/records, including form views, parent-child records, sharing and collaboration, advanced permissions, and Webhooks

General tools overview

Document creation and upload

Tool	Purpose
`create_file`	Create a new file in the cloud drive
`scrape_url`	Web page clipping: scrape web page content and automatically save it as a smart document
`scrape_progress`	Query web page clipping task progress
`upload_file`	Full upload to write files (update an existing docx/pdf or create and upload a local file)

Document reading and download

Tool	Purpose
`list_files`	Get the list of subfiles under the specified folder
`download_file`	Get file download information
`read_file_content`	Extract document content as Markdown/plain text

File organization

Tool	Purpose
`move_file`	Batch move files (folders)
`rename_file`	Rename files (folders)

Sharing and access

Tools	Purpose
`share_file`	Enable file sharing
`set_share_permission`	Modify sharing link properties
`cancel_share`	Cancel file sharing
`get_share_info`	Get sharing link information
`get_file_link`	Get the cloud document online access link for a file

Search

Tools	Purpose
`search_files`	File (folder) search

For complete parameters, examples, and return values, see references/drive.md。

Unsupported operations

No batch delete files tool (only move is supported)
The cloud drive side currently has no per-file ACL member matrix (sharing links are the main mechanism); for multi-dimensional tables (.dbt), see dbsheet.permission_* and dbsheet.share_* (see references/dbsheet.md for details)
For online Excel / smart sheet worksheet range protection, see the sheet.*_protection_ranges related tools (see references/sheet.md for details)
No file version rollback
No real-time collaborative editing control

Operation guide

Execution guide

Before performing the following operations,you mustfirst read the corresponding guide file:

Operation type	Guide file	When to read
File identifier retrieval guide	`references/file-locating-guide.md`	When you need to search or browse files
File reading guide	`references/file-reading-guide.md`	When you need to get document content
File creation and writing guide	`references/file-writing-guide.md`	When you need to create or edit a document

⚠️ Operating directly without reading the guide may cause: parameter errors, content loss, format anomalies.

High-frequency process guidance

Create and write a document

Execution order:

First, according to references/file-locating-guide.md get the target directory drive_id(optional),parent_id(optional).
Then, according to references/file-writing-guide.md select the document type and write path. Field passing: Step 1 obtains drive_id(optional),parent_id(optional), as the input for step 2, and executes the "new write" process.

Upload local files to the cloud drive