zspace-cli

zspace-cli

English · 简体中文

Manage your 极空间 (ZSpace) NAS from the terminal or AI agents — no password, no SSH, no DDNS.

mcp-name: io.github.skyzhao1223/zspace-cli

Just keep the ZSpace desktop client logged in on macOS.

📖 How large-file sliced upload was born: 一次 1.4GB 备份引发的逆向 (zh, CSDN) · CLI guide: 极空间 NAS 命令行管理指南 (zh, CSDN)

Beginner guide (no coding required) · Skills — incl. 9 cross-NAS organizer skills for AI agents · 中文文档

---

Install

pip install zspace-cli        # base

pip install "zspace-cli[mcp]" # optional MCP support zs check # ✓ reads the desktop client login state

Prerequisite: the ZSpace desktop client is running and logged in on macOS.

---

Quick start

zs ls /sata11/my/data/影视

zs find "权力的游戏" # full-text search zs tree /sata11/my/data -d 3 zs up ./本地文件.mp4 /sata11/my/data/影视 # upload zs up ./本地文件.mp4 /sata11/my/data/影视 --verify # upload + MD5 round-trip check zs down /sata11/my/data/影视/某文件.mkv ./下载 # download

from zspace_cli import ZSpaceClient

with ZSpaceClient() as zs: for f in zs.ls("/sata11/my/data"): print(f"{'📁' if f.is_dir else '📄'} {f.name}")

---

CLI options

zs check, zs ls, zs info, zs find, zs tree, zs usage, zs du, zs bigfiles, zs disks, zs smart, zs recycle list/config accept --json for machine-readable output. zs mv/zs cp/zs rm/zs down accept * ? glob patterns on the source path. zs baidu check/ls/tasks/fails also accept --json.

ls pages through large directories automatically (the NAS API returns at most 50 entries per call). find uses the NAS full-text index, so it searches across directories. Upload/download show a progress bar on a real terminal and stream the file (no full-file buffering). Pass --verify to zs up to download the uploaded file to a temporary directory and compare its MD5 with the local source; verification is opt-in because it doubles transfer. CJK paths work out of the box. Files above 64 MB are uploaded through the desktop client's sliced /v2/file/upload protocol (2 MB slices), because the local proxy rejects oversized single-request bodies with HTTP 413; a 413 on a smaller file falls back to slices automatically.

---

Features

---

Use with AI agents (Skills)

zs skill --list                           # see what's available

zs skill ~/your-project/.cursor/skills/ # install all (Cursor)

zs skill ~/your-project/skills/ # Claude Code, etc.

zs skill ~/your-project/skills/ --only nas-report,photo-organizer # or pick a few

Then tell your agent things like "list the files in /sata11/my/data". The skills ship inside the wheel, so zs skill works on any machine that has zspace-cli installed.

Besides zspace-nas (the zero-config base for ZSpace file ops), zs skill installs a family of 9 cross-NAS organizer skills. Their scanners are pure-stdlib and run on any mounted path (SMB/NFS), so they work with ZSpace, Synology, QNAP, UGREEN, etc. All follow the same read-only pattern: scan → the LLM drafts an old→new plan → you confirm → the agent executes (deletes always quarantine first).

Start with nas-report to see the big picture, then run whichever specialist it recommends. The most common combo is `dedup-finder` + `file-sorter`. De-duping first is *recommended* — you skip moving bytes you're about to delete, and you avoid same-name collisions — but the reverse order misses nothing: de-dup is content-level and independent of directory layout (verified: both orders find the identical duplicate groups). file-sorter reports suspected copies: X MB (N% of the bytes to move) so you can decide by the number instead of by a rule. See skills/README.md for the full list. Media-library naming stays a separate project: media-manager-skill.

---

How it works

ZSpace has no official CLI or public API. zspace-cli talks to the desktop client's local proxy, so it works behind NAT as long as the client is online:

Skill / zs / SDK / MCP  →  127.0.0.1:13579 (desktop client proxy)  →  NAS

Disclaimer — This is an unofficial, community-maintained project, not affiliated with or endorsed by ZSpace (极空间). It relies on the desktop client's local proxy interface, which is not officially documented. It only reads the login state of your own account on your own machine — it does not bypass authentication, crack encryption, or touch anyone else's data. Use at your own risk; make sure your use complies with the ZSpace user agreement and your local laws.

Platform support

Works on any OS where the ZSpace desktop client expose