Check whether the ZSpace NAS is reachable through the local desktop client proxy and, if so, return a summary of storage pools.

Call this first to verify the proxy at 127.0.0.1:13579 is online before running other file operations. Returns {"connected": true, "pools": [{name, total_tb, free_tb}]} when the NAS responds, or {"connected": false} when it does not. Never modifies NAS state.

Unlike zspace_pool_info, this is a connectivity probe that happens to include a pool summary; use pool_info when you only need capacity.

List every storage pool on the ZSpace NAS with its name and capacity.

Use to inspect free space before an upload or to report total capacity. Returns a list of {name, total_tb, free_tb} objects, one per pool. Read-only; never modifies NAS state.

Prefer this over zspace_disk_stats for capacity questions: it returns normalized per-pool numbers, whereas disk_stats returns the NAS's raw diagnostics object. Use zspace_check instead if you need to know whether the NAS is reachable at all.

Return raw disk statistics reported by the ZSpace NAS.

Use for diagnostics and health monitoring (I/O, capacity, SMART-style counters as exposed by the NAS API). Returns the raw stats object. Read-only; never modifies NAS state.

Unlike zspace_pool_info, the shape is whatever the NAS API exposes and is not normalized — choose pool_info for "how much free space", this one for "is a disk unhealthy".

List the contents of a directory on the ZSpace NAS at the given path.

Use to browse files, locate items, or pick targets for later move/copy operations. Large directories are paginated automatically (the NAS API returns at most 50 entries per call). Returns a list of {name, path, is_dir, size} objects. Read-only; pass show_hidden=True to include hidden entries.

Flat and one level deep: use zspace_tree for nested structure, zspace_search when you know a name but not the location, and zspace_info for full metadata on one path you already have.

Return detailed metadata for one file or directory on the ZSpace NAS.

Use when you need more than the ls summary exposes (permissions, timestamps, exact size, type details). Returns the raw info object from the NAS API. Read-only; the path must already exist.

One path only — use zspace_ls to enumerate a directory, or zspace_search to locate an item first.

Rename one file or directory on the ZSpace NAS, keeping it in place.

Use to fix a name without changing location; the parent directory stays the same. new_name is the bare basename, not a path. Returns the updated {name, path}. This mutates NAS state; it cannot be undone.

Same-directory only — use zspace_move to relocate to a different parent (move also accepts several paths at once, rename does not).

Create a new directory on the ZSpace NAS under the given parent.

Use to prepare a destination before moving files into it. name is the bare basename, not a path. Fails if a directory of that name already exists. Returns the created {name, path}. Mutates NAS state.

zspace_move and zspace_copy both require the destination to exist already, so call this first when reorganizing into a new folder.

Move one or more files/directories on the NAS into a destination folder.

Use to reorganize files, e.g. sort media into per-genre folders. Accepts a single path or a list; the destination must already exist (create it with zspace_mkdir). Returns {status: "moved", paths, to}. Mutates NAS state; sources are removed from their original location.

Choose move vs copy by whether the originals should survive: copy keeps them, move does not. To change only the name within the same directory, use zspace_rename instead.

Copy one or more files/directories on the NAS into a destination folder.

Use to duplicate media or create backups without removing the originals. Accepts a single path or a list; the destination must already exist (create it with zspace_mkdir). Returns {status: "copied", paths, to}. Mutates NAS state but leaves the sources untouched.

The non-destructive counterpart of zspace_move — pick copy when the original must stay where it is, move when it should not. Copies consume additional capacity; check zspace_pool_info first for large trees.

Permanently delete one or more files/directories from the ZSpace NAS.

Use only when you are sure the items are no longer needed — deletion is immediate and NOT recoverable. Accepts a single path or a list. Returns {status: "removed", paths}. Marked destructive: confirm intent before calling.

There is no trash or undo: zspace_move is the reversible alternative when the goal is only to get items out of the way. Confirm the exact paths with zspace_ls or zspace_search before calling, and never pass a pool root.

Search for files/directories on the NAS whose names contain the keyword.

Use to find a file without knowing its exact location. Returns a list of {name, path, is_dir} matches, capped at 100. Read-only; never modifies NAS state.

The NAS full-text index is searched GLOBALLY, then results are filtered client-side to path. Because path defaults to /sata11/my/data, a match living in another pool is silently dropped and you get an empty list — pass the pool root (or the widest directory you mean) before concluding a file does not exist. Unlike zspace_ls / zspace_tree this matches by name across the index rather than walking a directory.

Return a nested tree view of a directory on the ZSpace NAS.

Use to understand overall folder structure before deep operations. depth caps recursion (default 2). Returns the nested tree structure as exposed by the NAS API. Read-only.

Nested rather than flat: use zspace_ls for a single level with sizes, or zspace_search when you are looking for a name rather than a layout.

Upload a file from the local machine to a directory on the ZSpace NAS.

Use to push media or documents to the NAS. remote_dir must already exist (create it with zspace_mkdir); pass new_name to rename it on arrival. Returns the upload result from the NAS API. Mutates NAS state; a file with the same name is overwritten.

Local -> NAS, the inverse of zspace_download. Files above 64 MB go through the desktop client's sliced upload protocol (2 MB slices) automatically, because the local proxy rejects oversized single-request bodies with HTTP 413. Check zspace_pool_info for free space before large uploads.

Download a file from the ZSpace NAS to a local directory.

Use to pull media or documents off the NAS. The local_dir must already exist. Returns {saved_to: ""}. Does not modify NAS state.

NAS -> local, the inverse of zspace_upload. Unlike upload this never changes anything on the NAS, so it is safe to retry; an existing local file of the same name is overwritten.