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:

Login to https://docz.zhenguanyu.com (SSO)
Go to Settings → Account → API Tokens (or visit /settings directly)
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
`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

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 user@co.com

# 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_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`
`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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docz-cli

Quick Start

Features

Installation

Authentication

Commands

Usage Examples

Browse

Short URL

Write

Manage

Comments

Share Links

Diff

Pipes

MCP Server

Configuration

MCP Tools

AI Agent Skill

API Reference

Contributing

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

docz-cli

Quick Start

Features

Installation

Authentication

Commands

Usage Examples

Browse

Short URL

Write

Manage

Comments

Share Links

Diff

Pipes

MCP Server

Configuration

MCP Tools

AI Agent Skill

API Reference

Contributing

License