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. 8 cross-NAS organizer skills for AI agents ยท ไธญๆๆๆกฃ
Install
pip install zspace-cli
pip install "zspace-cli[mcp]"
zs check
Prerequisite: the ZSpace desktop client is running and logged in on macOS.
Quick start
zs ls /sata11/my/data/ๅฝฑ่ง
zs find "ๆๅ็ๆธธๆ"
zs tree /sata11/my/data -d 3
zs up ./ๆฌๅฐๆไปถ.mp4 /sata11/my/data/ๅฝฑ่ง
zs down /sata11/my/data/ๅฝฑ่ง/ๆๆไปถ.mkv ./ไธ่ฝฝ
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
| Command | Meaning |
|---|
zs check | Verify the desktop client proxy is reachable |
zs ls [path] | List directory (-a/--hidden, -l/--long) |
zs info <path> | Detailed file/dir info |
zs rename <path> <new> | Rename a file or directory |
zs mv <src> <dest> | Move a file/directory |
zs cp <src> <dest> | Copy a file/directory |
zs mkdir <parent> <name> | Create a directory |
zs rm <path> | Delete (-f/--force skips confirmation) |
zs find <keyword> [path] | Full-text search across the NAS |
zs tree [path] | Tree view (-d/--depth N, default 2) |
zs up <local> <remote_dir> | Upload (-n/--name to rename remotely; large files auto-switch to sliced upload) |
zs down <path> [dir] | Download |
zs skill <dir> | Copy Agent skills into a project (--list, --only a,b) |
zs --config-dir <dir> | Point at a non-default vuex.json location (or ZS_CONFIG_DIR) |
zs check, zs ls, zs info, zs find, zs tree accept --json for
machine-readable output. zs mv/zs cp/zs rm/zs down accept * ? glob
patterns on the source path.
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). 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
| Operation | CLI | SDK | MCP |
|---|
| List directory | zs ls [path] | client.ls(path) | zspace_ls |
| File info | zs info <path> | client.info(path) | zspace_info |
| Rename | zs rename <path> <name> | client.rename(path, name) | zspace_rename |
| Create dir | zs mkdir <parent> <name> | client.mkdir(parent, name) | zspace_mkdir |
| Move | zs mv <src> <dest> | client.move(src, dest) | zspace_move |
| Copy | zs cp <src> <dest> | client.copy(src, dest) | zspace_copy |
| Delete | zs rm <path> | client.remove(path) | zspace_remove |
| Search | zs find <keyword> | client.search(kw) | zspace_search |
| Tree view | zs tree [path] | client.tree(path) | zspace_tree |
| Upload | zs up <local> <dir> | client.upload(local, dir) | zspace_upload |
| Download | zs down <path> [dir] | client.download(path, dir) | zspace_download |
| Health check | zs check | client.is_connected() | zspace_check |
Use with AI agents (Skills)
zs skill --list
zs skill ~/your-project/.cursor/skills/
zs skill ~/your-project/skills/ --only nas-report,photo-organizer
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 8 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).
| Skill | What it does |
|---|
| nas-report | ๐งญ Entry point: whole-disk storage profile + routes you to the right specialist skill |
| photo-organizer | Photos/videos: file by shoot date, screenshots/WeChat images, burst de-dup |
| music-organizer | Music: Artist/Album/Track structure, track numbers, covers, built-in ID3v2 parsing |
| work-organizer | Work files: archive loose files, version chaos, copies, stale-file archiving |
| portfolio-organizer | Portfolio: project structure, cover/README, separate finals from sources |
| download-cleaner | Downloads: triage & clean (partials/torrents/installers/archives/unsorted media) |
| dedup-finder | Content-level exact de-dup (3-stage fingerprint sizeโheadโfull sha1, zero false positives) |
| backup-auditor | Backup health: version rotation, staleness, coverage check |
Start with nas-report to see the big picture, then run whichever specialist it recommends. 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.
Works on any OS where the ZSpace desktop client exposes its local proxy on
127.0.0.1:13579. The login state (vuex.json) is auto-detected:
| Platform | Default location |
|---|
| macOS | ~/Library/Application Support/zspace/vuex.json |
| Windows | %APPDATA%\zspace\vuex.json (also tries %LOCALAPPDATA%, %USERPROFILE%) |
| Linux | ~/.zspace/vuex.json, ~/.config/zspace/vuex.json (best-effort) |
If the client stores it elsewhere, point the CLI/SDK at it explicitly:
zs --config-dir ~/path/to/zspace-config check
ZS_CONFIG_DIR=~/path/to/zspace-config zs check
Windows/Linux config locations are best-effort guesses (not verified against
a real client). If auto-detection misses yours, please open an issue with the
actual path so it can be added.
Windows on ARM โ some [mcp] dependencies (e.g. cryptography) don't ship
ARM64 wheels for every version, so pip install "zspace-cli[mcp]" may try to
build them from source (slow, or fails without Rust). Force prebuilt wheels:
pip install --only-binary=:all: "zspace-cli[mcp]".
MCP configuration (optional)
{
"mcpServers": {
"zspace": { "command": "zs-mcp", "args": [] }
}
}
Docker (headless)
Run the CLI / MCP server in a container and talk to the desktop client proxy
on the host โ no desktop client needed inside the image:
export ZS_CONFIG_HOST_DIR="$HOME/Library/Application Support/zspace"
docker compose build
docker compose run --rm zspace-cli zs check
docker compose run --rm zspace-cli zs ls /sata11/my/data
It mounts the host's ZSpace config read-only (ZS_CONFIG_HOST_DIR) and points
ZS_BASE_URL at the host via host.docker.internal. On Linux hosts, either use
network_mode: host or the included extra_hosts mapping. For a plain
container run:
docker build -t zspace-cli .
docker run --rm --network host \
-e ZS_BASE_URL=http://127.0.0.1:13579 \
-e ZS_CONFIG_DIR=/config \
-v "$HOME/Library/Application Support/zspace:/config:ro" \
zspace-cli zs check
Globbing
rm / mv / cp / down accept glob patterns (*, ?, [...], **) that
are expanded on the NAS:
zs rm "/sata11/my/data/ๅฝฑ่ง/*.mkv" --force
zs cp "/sata11/my/data/**/*.mp4" /sata11/my/data/movies
zs down "/sata11/my/data/photos/*.jpg" ./photos
Or via the SDK: client.glob("/sata11/my/data/**/*.mkv").
API reference
| Endpoint | Key Parameters |
|---|
/v2/file/list | path, show_hidden, start, limit |
/v2/file/info | path |
/v2/file/modify | path, newname |
/v2/file/newdir | parent, name, rename=0 |
/v2/file/move / copy | paths[], to |
/v2/file/remove | paths[] |
/v2/file/create | binary body, header path as UTF-8 bytes (small-file upload; proxy returns 413 above a size cap) |
/v2/file/upload | sliced upload: query uuid=md5(mtime_ms+size+target_path), headers seek/split=1/size/path per 2 MB slice |
/v2/file/download | GET path, remote_port=8050 |
/file_search/file_search | keyword |
Note: the interface parameter names are non-standard (parent / to instead of path / dest) โ documented by the community from the desktop client's behavior.
Repository layout
zspace-cli/
โโโ src/zspace_cli/
โ โโโ cli.py # Typer CLI (zs ...)
โ โโโ client.py # ZSpaceClient SDK (retry / stream / progress)
โ โโโ auth.py # vuex.json auto-detection + credential cache
โ โโโ mcp_server.py # MCP tools (zs-mcp)
โ โโโ skills/ # packaged skill copies shipped in the wheel (keep in sync!)
โโโ skills/ # skill sources โ the source of truth (edit here)
โโโ scripts/mcp_smoke.py
โโโ tests/ # pytest (CLI + SDK + MCP + auth)
โโโ promo/ # launch/promo material (submodule)
Integrations
Pair zspace-cli with Jellyfin / Emby / MoviePilot / MCP clients / Docker and media-manager-skill for media library tooling.
For cloud-drive โ NAS pipelines, combine with baidu-pan-skill: it downloads Baidu NetDisk (็พๅบฆ็ฝ็) share links reliably (cookie extraction, transfer-save, resumable chunked downloads, structural verification), then zs up takes over for the sliced large-file upload to the NAS. Both ship as agent skills, so one prompt can drive the whole backup.
Roadmap
Contributing
PRs welcome โ see
CONTRIBUTING.md for dev setup, quality gates, and the
skill-authoring guide (including the skills/ โ src/zspace_cli/skills/
dual-copy sync rule that CI enforces).
Legal
Unofficial community project, not affiliated with or endorsed by ZSpace/ๆ็ฉบ้ด.
It automates your own logged-in desktop client on your own machine โ
no passwords handled, no service gates bypassed (membership-gated features are
documented as gated, never worked around). API notes are interoperability
documentation of observed client behavior and may break with client updates.
Concerns or takedown requests: skyzhao1223@users.noreply.github.com โ
legitimate requests are answered promptly. Source archives ship with every
GitHub Release; the maintainer keeps off-platform git bundle mirrors.
License
MIT
