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 <space>:<from> <to> | Rename or move | | log <space>[:<path>] | Show change history | | rollback <space>:<path> <commit> | Rollback file to a specific commit | | shortlink <space>:<path> | Get short URL for file | | 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> | Show share link info | | 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

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://...)

Manage

docz-cli mv G160-研发:old.md new.md              # Rename
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

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
docz-cli share info xYz123AbC

# 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