zspace-cli

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

Just keep the ZSpace desktop client logged in on macOS.

中文文档 · Skills

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 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}")

Use with AI agents (Skills)

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

Then tell your agent things like "list the files in /sata11/my/data". See skills/README.md for the full skill list.

Features

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.

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 exposes its local proxy on 127.0.0.1:13579. The login state (vuex.json) is auto-detected:

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   # or as an env var

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.

MCP configuration (optional)

{
  "mcpServers": {
    "zspace": { "command": "zs-mcp", "args": [] }
  }
}

API reference

Note: the interface parameter names are non-standard (parent / to instead of path / dest) — documented by the community from the desktop client's behavior.

Roadmap

• File upload/download
• Linux / Windows client auth (best-effort path detection + ZS_CONFIG_DIR)
• Docker headless option
• Batch glob helpers

Contributing

Open an issue first to discuss changes. PRs welcome.

License

MIT