Kdocs CLI Tool

The Specific Problem It Solves

When building automation scripts, data pipelines, or integrating tools, interacting with Kingsoft Docs (WPS Cloud documents, spreadsheets, presentations, etc.) via a traditional web UI is inefficient and difficult to scale. Developers require a reliable, programmable way to manage cloud document assets—performing tasks like batch creation, content extraction, formatted updates, and sharing permission control—while ensuring operational security (e.g., no credential leaks) and process verifiability.

How the Skill Works

The Kdocs CLI Skill provides a comprehensive command-line toolset (kdocs-cli) that acts as a local proxy to interact with Kingsoft Docs' RESTful APIs. Its core functionality revolves around these capabilities:

• Comprehensive Document Type Support: It handles not just traditional .docx, .xlsx, .pptx, but also deeply integrates with Kingsoft's own Smart Docs (.otl), Smart Sheets (.ksheet), and Multi-dimensional Tables (.dbt). Each type has a dedicated reference (e.g., references/otl.md) defining its unique operations.
• Standardized Command-Line Invocation: All operations are initiated via the unified format kdocs-cli <service> <action> [parameters]. Parameter passing is flexible, supporting simple key=value forms, direct JSON strings, or reading complex/large JSON payloads from a file via the --file parameter, bypassing command-line length limits and encoding issues.
• Strict Operational Safety and Verification: The skill enforces a set of rules. For instance, it prohibits exposing Tokens in any dialog or log in plaintext; they must be stored in the system keychain via kdocs-cli auth set-token. For irreversible operations like delete or close, a secondary user confirmation is mandatory before execution. Any write operation (e.g., updating a cell, inserting a paragraph) must be followed by a separate read request to verify the result, rather than relying on the API's success status code.
• Intelligent File Location and Workflows: For processing existing documents, it provides a complete lookup chain. You can search via keyword with search_files, or use the hierarchical browsing methods described in references/file-locating-guide.md. For common tasks (like "search-read-report"), predefined workflows (e.g., references/workflows/search-read-report.md) can be followed.

Applicable Boundaries and Key Considerations

• Environment and Version Dependencies: It is a CLI tool that requires local installation (via scripts like scripts/setup.sh). On first use or if more than 24 hours have passed since the last use, you must check and ensure both the kdocs-cli and the Skill itself are at the latest version to avoid errors like unknown action/service. If upgrades fail, there are rollback and reinstallation mechanisms.
• Rigorous Parameter Passing: When parameters contain Chinese, multiline text, or exceed 200 characters, you must use the --file or stdin methods to pass a JSON file, and avoid key=value or native JSON serialization from certain languages (like PowerShell) to prevent encoding corruption. Using Node.js or Python to generate JSON files is recommended.
• Error Handling and Rate Limiting: Errors like authentication failure (400006), request rate limiting (429001), or service circuit-breaking (429002) may be encountered. Upon hitting a rate limit, you must wait for the recovery time specified in the response; immediate retries are prohibited. Retry strategies vary based on the idempotency of different tools, which should be checked in the respective tool's reference documentation.
• Capability Boundaries: It is primarily for operating on Kingsoft Docs, not for rendering or presenting document content. Its output is structured JSON data or status messages. If an expected function is not found in kdocs-cli --help, the first step should be to upgrade, as new capabilities are continuously added with versions.