docz-cli

DocSync CLI & MCP Server — read and write company documents from terminal and AI agents

Quick Start

# Login
npx docz-cli@latest login --token <your-token>

# Browse
npx docz-cli@latest spaces
npx docz-cli@latest ls G160-研发
npx docz-cli@latest cat G160-研发:docs/guide.md

# Write
npx docz-cli@latest write 吴鹏飞:notes/todo.md '# TODO List'

Features

• Simple addressing — <space>:<path> format, Space supports name, slug, or UUID (suffix match: "研发" → "G160-研发")
• Short URL support — paste https://docz.xxx.com/s/slug/f/fileId directly into cat/ls/log, or generate with shortlink
• Full file operations — ls, cat, upload, write, mkdir, rm, mv
• Share links — create, list, update, access, delete share links from CLI
• File diff — view file-level unified diff or space-level change summary
• Git-backed — every write creates a commit, built-in version history
• Trash recovery — deleted files recoverable within 30 days
• MCP Server — built-in stdio MCP server for AI agent integration
• Zero config — single token, works immediately

Installation

Requirements: Node.js >= 22.0.0

npx docz-cli@latest <command>   # Always uses the latest version (recommended)
npm install -g docz-cli          # Or global install, then use `docz` shorthand

Auto-update: Using npx docz-cli@latest ensures you always run the latest version without manual updates. Global install requires npm update -g docz-cli to update.

Global install registers both docz-cli and docz commands. Examples below use docz-cli; replace with docz if installed globally.

Authentication

Get your API Token:

1. Login to https://docz.zhenguanyu.com (SSO)
2. Go to Settings → Account → API Tokens (or visit /settings directly)
3. Click New Token, name it, copy the token (shown only once)

Then configure:

# Option 1: login command (saved to ~/.docz/config.json)
docz-cli login --token <your-token>

# Option 2: environment variable
export DOCSYNC_API_TOKEN=<your-token>

Commands

| Command | Description | |---------|-------------| | login --token <t> | Configure credentials | | whoami | Show current user | | spaces | List all accessible spaces (name, type, members, UUID, slug) | | ls <space>[:<path>] | List files and folders | | cat <space>:<path> | Read file content | | upload <file> <space>[:<dir>] | Upload local file | | image upload <file> | Upload image to OSS, get permanent public URL for Markdown | | write <space>:<path> <content> | Write content to file (- for stdin) | | mkdir <space>:<path> | Create folder | | rm <space>:<path> | Delete file/folder (30-day trash) | | mv <source> <destination-path> | Rename or move within a Space | | log <space>[:<path>] | Show change history | | rollback <space>:<path> <commit> | Rollback file to a specific commit | | shortlink <space>:<path> | Get short URL for file | | link info <url> [--json] | Inspect ordinary link, Space permission, path, and document status | | local root [--json] | Print the configured local synchronization root | | sheet get <target> --range <sheet!a1> | Read a range from the live Univer collaboration state | | sheet set <target> --range <sheet!a1> --values-json <matrix> | Write a range through Univer OT and confirm the result | | trash <space> | Show deleted files | | restore <space>:<path> <commit> | Restore file from trash | | diff <space>[:<path>] <commit> [<from>] | Show changes (file or space level) | | comment list <space>:<path> | List comments on a file | | comment add <space>:<path> <msg> | Add comment to a file | | comment reply <space> <id> <msg> | Reply to a comment | | comment close <space> <id> | Close a comment | | comment rm <space> <id> | Delete a comment | | share create <space>:<path> | Create share link | | share list <space> | List share links | | share update <space> <link-id> | Update share link | | share cat <token-or-url> | Read shared file | | share info <token-or-url> [--json] | Inspect share lifecycle, access, and target status | | share rm <space> <link-id> | Delete share link | | mcp | Start MCP stdio server |

Usage Examples

Browse

docz-cli whoami                         # Show current user info
docz-cli spaces                         # List all spaces (with slug)
docz-cli ls G160-研发                    # List root directory
docz-cli ls G160-研发:docs               # List subdirectory
docz-cli ls -R G160-研发                 # List all files recursively
docz-cli cat G160-研发:docs/guide.md     # Read file content
docz-cli cat --ref G160-研发:docs/guide.md  # Read file + show git ref

Short URL

Generate a short URL for any file, or paste existing short URLs directly into any command:

# Generate short URL
docz-cli shortlink 闫洪康:AI-Coding技巧总结12.md
# → https://docz.zhenguanyu.com/s/yanhongkang/f/NNjrcj8c

# Short URLs work with cat, ls, log, diff, rm, etc.
docz-cli cat https://docz.zhenguanyu.com/s/yanhongkang/f/NNjrcj8c
docz-cli ls https://docz.zhenguanyu.com/s/yanfa
docz-cli log https://docz.zhenguanyu.com/s/yanhongkang/f/NNjrcj8c

# A directory short URL can address a child below its canonical directory
docz-cli cat https://docz.zhenguanyu.com/s/yanhongkang/f/DirectoryId/nested/guide.md

/s/{slug}/f/{fileId}/... is always a stable-reference route. The fileId must resolve to a directory before a child path is accepted; invalid references, Space mismatches, file references with suffixes, and traversal-like child paths fail before the document operation. To access a literal Space-root path that starts with f/, use the unambiguous space:f/... form.

For upload, the complete child path remains a destination directory, exactly like space:dir; the local basename is appended by the command. For mv, only the source accepts a URL and the destination remains a complete path relative to the Space root, not relative to the stable directory.

Link Metadata

Ordinary and share links use separate commands and output contracts. Link lifecycle and target document status are reported independently.

# Ordinary stable/path/root/legacy links (authentication required)
docz-cli link info https://docz.zhenguanyu.com/s/yanfa/f/NNjrcj8c
docz-cli link info https://docz.zhenguanyu.com/s/yanfa/f/DirectoryId/nested/guide.md --json
docz-cli link info https://docz.zhenguanyu.com/s/yanfa/docs/guide.md --json

# Share token or URL (public shares can be inspected without a token)
docz-cli share info https://docz.zhenguanyu.com/share/xYz123AbC
docz-cli share info xYz123AbC --json

Ordinary JSON includes link_status, space_permission, document_path, document_status, space_admin, and is_folder. Share JSON additionally uses share-specific fields such as access_status, visibility, role, shared_by, and expires_at. Technical failures produce unknown values and exit code 2 instead of incorrectly reporting a missing link or document.

Local Sync Root

docz local root
docz local root --json
DOCSYNC_CLIENT_DATA_DIR=/custom/client-data docz local root --json

This command only reads sync_dir from the local DocSync client configuration. It does not connect to the daemon, enumerate or read synchronized files, or claim that the local copy is current. JSON therefore reports "freshness":"unknown". If the configured root is missing, the command still prints the path and exits with code 2.

AI agents must ask for task-scoped user confirmation before searching or reading files below this root. The synchronized directory is always read-only to agents: existing documents are edited through collab cat/write, new text documents through write, and other mutations through the corresponding Docz CLI commands.

Write

docz-cli write 吴鹏飞:notes/todo.md '# TODO List'                    # Write content
docz-cli write --force 吴鹏飞:notes/todo.md '# Updated'              # Skip conflict detection
echo '# Report' | docz-cli write 吴鹏飞:reports/daily.md -            # From stdin
docz-cli upload ./report.pdf G160-研发:reports                         # Upload file
docz-cli mkdir G160-研发:new-project                                   # Create folder

Images

Upload images to OSS for embedding in Markdown documents. Returns a permanent public URL — visible in share links and blogs without login, and doesn't consume Space quota. Supports png/jpg/webp, max 5MB.

docz-cli image upload ./screenshot.png
# URL: https://<bucket>.oss-cn-beijing.aliyuncs.com/docz-markdown/2026/06/.../image.png
# Markdown: ![screenshot](https://...)

Realtime text collaboration

docz collab cat <target> > current.md 2> current.meta
docz collab write <target> - --base-collab-hash <hash> < edited.md
docz collab publish <target>

Use the collab_hash from the live read, merge your changes into that content, then write. Commands negotiate the collaboration session and follow stable file identities when enabled; legacy text rooms remain supported. Sheet descriptors use sheet get/set, not text collaboration. --no-publish waits for realtime update acknowledgement but does not explicitly flush to Git (server autosave can still occur).

Exit 1 means the command failed; exit 75 means the edit/publish result is unknown. On 75, preserve your draft and reread before deciding whether another write is needed. Do not blindly replay it. A failed publish does not roll back an edit already sent to the realtime room. Connection failures before editing are reported separately. A server's generic permission-denied is reported as an ambiguous authentication rejection because older servers mask other failures.

See protocol and validation notes for compatibility, error categories, and the minimal server-side error propagation follow-up.

Univer Sheets

Sheet commands read and write the current Univer collaboration state; they do not edit the .sheet.json descriptor or a stale Git snapshot. Session roles use Univer's mapped names: Docz owner → owner, member → editor, and viewer → reader; user-facing permissions below remain expressed as Docz Space roles.

docz-cli sheet get G160-研发:reports/Budget.sheet.json \
  --range 'Sheet1!A1:B2' --json

docz-cli sheet set G160-研发:reports/Budget.sheet.json \
  --range 'Sheet1!A1:B2' \
  --values-json '[["name","amount"],["demo",3014]]' \
  --request-id '4e8c29b7-f3e8-4db5-86ae-0878dc1fa88c' \
  --timeout 30000 --json

--values-json must be a rectangular two-dimensional JSON matrix matching the requested range. The maximum per-phase timeout is 30000 ms. A stable --request-id makes audit lookup and reconciliation safe, but replaying an uncertain request never sends a second mutation automatically.

Exit codes are 0 for SYNCED, 1 for definite FAILED, and 2 for UNKNOWN. UNKNOWN means the write may have reached Univer but the CLI could not observe the state cycle and matching collaboration revision acknowledgement. Reread the range before deciding whether to retry; do not retry blindly.

Every --json result includes identity_resolved. It is false with unit_id: null when the CLI could not resolve a canonical Sheet session, and true once space_id, path, and unit_id identify the canonical session or an existing operation—even when a later read, write, or confirmation phase fails.

failure_code is a bounded machine value and never contains the raw upstream error. Callers should handle these groups:

• Input/session: authentication_required, sheet_arguments_invalid, sheet_target_invalid, sheet_path_required, sheet_timeout_invalid, sheet_range_invalid, sheet_write_invalid_values
• Authorization/transport: collaboration_permission_denied, sheet_write_forbidden, collaboration_timeout, collaboration_unavailable, collaboration_conflict, initial_load_failed
• Read/write SDK: sheet_read_failed, sheet_worksheet_not_found, sheet_write_command_rejected, sheet_write_sdk_incompatible, sheet_write_command_failed
• Operation/confirmation: operation_begin_unconfirmed, operation_range_unbound, sheet_identity_changed, operation_execution_not_claimed, pending_timeout, sync_confirmation_lost, sdk_rejected, interrupted_before_mutation, interrupted_after_mutation

Resolution-time authentication and network failures retain their permission or transport code; only a genuinely invalid or missing target uses sheet_target_invalid.

Manage

docz-cli mv G160-研发:old.md new.md                   # Rename in the Space root
docz-cli mv G160-研发:docs/old.md archive/new.md      # Move and rename
docz-cli mv https://docz.example.com/s/abc/docs/old.md docs/new.md # URL source
docz-cli rm G160-研发:deprecated.md               # Delete (recoverable for 30 days)
docz-cli log G160-研发                             # Space history
docz-cli log G160-研发:docs/guide.md              # File history
docz-cli rollback G160-研发:docs/guide.md abc1234  # Rollback file to a specific commit
docz-cli trash G160-研发                           # View deleted files
docz-cli restore G160-研发:deleted.md del1234      # Restore file from trash

mv 的第二个参数是相对于 Space 根目录的完整目标路径（包含最终文件名）， 不是相对于源文件所在目录的路径。目标父目录必须已存在。

Comments

docz-cli comment list G160-研发:docs/guide.md             # List comments on a file
docz-cli comment add G160-研发:docs/guide.md '需要补充说明'  # Add comment
docz-cli comment reply G160-研发 42 '已补充'               # Reply to comment #42
docz-cli comment close G160-研发 42                        # Close comment #42
docz-cli comment rm G160-研发 42                           # Delete comment #42

Share Links

# Create (with optional expiry and visibility)
docz-cli share create G160-研发:docs/guide.md --expires 7d --users [email protected]

# List all share links in a space
docz-cli share list G160-研发
docz-cli share list G160-研发 --file docs/guide.md    # Filter by file

# Access shared content (token or full URL)
docz-cli share cat xYz123AbC
docz-cli share cat https://docz.zhenguanyu.com/share/xYz123AbC
docz-cli share cat xYz123AbC --raw | grep "部署"  # Raw output for pipes

# View share link info (human or JSON)
docz-cli share info xYz123AbC
docz-cli share info xYz123AbC --json

# Update and delete (requires space context)
docz-cli share update G160-研发 <link-id> --expires 30d
docz-cli share rm G160-研发 <link-id>

Diff

# View what changed in a commit (file level)
docz-cli diff G160-研发:docs/guide.md af0fb9b

# Compare two commits
docz-cli diff G160-研发:docs/guide.md af0fb9b b2c3d4e

# Space-level: which files changed in a commit
docz-cli diff G160-研发 af0fb9b

# Typical workflow: log → pick commit → diff
docz-cli log G160-研发:docs/guide.md
docz-cli diff G160-研发:docs/guide.md af0fb9b

Pipes

cat outputs to stdout, write ... - reads from stdin. Combine with any Unix tool:

# Search content
docz-cli cat G160-研发:docs/guide.md | grep "部署"

# Extract CSV columns
docz-cli cat G160-研发:data.csv | cut -d',' -f1,3 | head -10

# Read → transform → write back
docz-cli cat 吴鹏飞:config.md | sed 's/old/new/g' | docz-cli write 吴鹏飞:config.md -

# Local command output → DocSync
echo "# Generated at $(date)" | docz-cli write 吴鹏飞:notes/auto.md -
cat local-file.md | docz-cli write 吴鹏飞:docs/remote.md -

MCP Server

Built-in MCP server for AI agent integration (Claude Code, Cursor, etc.).

Configuration

Add to your MCP settings:

{
  "mcpServers": {
    "docz-mcp": {
      "command": "npx",
      "args": ["-y", "docz-cli@latest", "mcp"],
      "env": {
        "DOCSYNC_API_TOKEN": "<your-token>"
      }
    }
  }
}

Using docz-cli@latest in MCP config ensures AI agents always use the latest version.

MCP Tools

| Tool | Description | |------|-------------| | docz_list_spaces | List all accessible spaces | | docz_list_files | List files in a directory | | docz_read_file | Read file content | | docz_upload_file | Upload/create a file | | docz_upload_image | Upload image to OSS, returns public URL for Markdown | | docz_mkdir | Create a folder | | docz_delete | Delete file/folder | | docz_file_history | View change history | | docz_share_create | Create share link | | docz_share_list | List share links | | docz_share_read | Read shared file by token | | docz_share_info | View share link info | | docz_share_delete | Delete share link | | docz_shortlink | Get short URL for file | | docz_diff | View file or space diff |

AI Agent Skill

Install as a reskill skill to teach AI agents how to use docz-cli:

npx reskill install github:kanyun-inc/docz-cli/skills -a claude-code cursor -y

The skill provides command reference, usage scenarios, and addressing format documentation so agents can autonomously browse, read, and write DocSync documents.

API Reference

docz-cli wraps the DocSync REST API:

| Command | API Endpoint | |---------|-------------| | spaces | GET /api/spaces | | ls | GET /api/spaces/{id}/tree?path= | | cat | GET /api/spaces/{id}/blob/{path} | | upload / write | POST /api/spaces/{id}/files/upload or POST /api/spaces/{id}/files/save | | image upload | POST /api/assets/images | | mkdir | POST /api/spaces/{id}/files/mkdir | | rm | POST /api/spaces/{id}/files/delete | | mv | POST /api/spaces/{id}/files/rename | | log | GET /api/spaces/{id}/log/[{path}] | | rollback | POST /api/spaces/{id}/files/rollback | | trash | GET /api/spaces/{id}/trash | | restore | POST /api/spaces/{id}/trash/restore | | diff | GET /api/spaces/{id}/diff/[{path}]?from=&to= | | comment list | GET /api/spaces/{id}/comments?path= | | comment add | POST /api/spaces/{id}/comments | | comment reply | POST /api/spaces/{id}/comments/{commentId}/replies | | comment close | PUT /api/spaces/{id}/comments/{commentId} | | comment rm | DELETE /api/spaces/{id}/comments/{commentId} | | share create | POST /api/spaces/{id}/share-links | | share list | GET /api/spaces/{id}/share-links | | share update | PUT /api/spaces/{id}/share-links/{linkId} | | share cat | GET /api/share/{token} | | share info | GET /api/share/{token}/info | | share rm | DELETE /api/spaces/{id}/share-links/{linkId} | | shortlink | GET /api/spaces/{id}/file-ref?path= | | Short URL resolve | GET /api/spaces/by-slug/{slug} + GET /api/file-refs/{fileId} |

Auth: Authorization: Bearer <token>. Backend is Git — every write is a commit.

Contributing

See CONTRIBUTING.md. Quick version:

# New branch
git checkout -b feature-xxx

# Code + tests
pnpm typecheck && pnpm lint && pnpm test && pnpm build

# Add a changeset (skipping this means no release)
pnpm changeset

# Open a PR

Once merged into main, GitHub Actions automatically bumps the version and publishes to npm — no manual npm publish, no tag, no OTP.

License

MIT