> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Filesystem

> Python SDK object reference for machine files, uploads, downloads, search, and watches.

`machine.files` operates on machine-scoped absolute paths. `/workspace` is the
default mutable work tree for repo-style flows, but general file APIs also
accept valid paths such as `/tmp/...`, `/data/...`, and `/srv/app/...`.

## File CRUD

| Method                                                 | Use                                           |
| ------------------------------------------------------ | --------------------------------------------- |
| `read(path, format="text")`                            | Read a file as text or bytes.                 |
| `write(path, data)`                                    | Write text or bytes to a file.                |
| `write_files(items)`                                   | Write many files and report partial failures. |
| `list(path)` / `info(path)` / `exists(path)`           | Inspect paths and metadata.                   |
| `make_dir(path)` / `rename(src, dst)` / `remove(path)` | Manage directories and files.                 |
| `set_permissions(path, mode)`                          | Update POSIX-style permissions.               |

## Transfers

| Method                                       | Use                                                     |
| -------------------------------------------- | ------------------------------------------------------- |
| `upload_file(source, destination=None, ...)` | Upload one local file.                                  |
| `upload_dir(source, destination=None, ...)`  | Upload a local directory as a resumable tar transfer.   |
| `upload(source, destination=None, ...)`      | Dispatch based on local source type.                    |
| `resume_upload(upload_id, source, ...)`      | Resume a failed resumable upload.                       |
| `download_file(path, local_path, ...)`       | Download one machine file.                              |
| `download_dir(path, local_path, ...)`        | Download a directory archive and optionally extract it. |
| `upload_url(path)` / `download_url(path)`    | Create signed direct-transfer URLs.                     |

## Search And Watch

| Method                                             | Use                                   |
| -------------------------------------------------- | ------------------------------------- |
| `find_files(root, pattern)`                        | Find file names by pattern.           |
| `search_files(root, pattern)`                      | Search file contents.                 |
| `replace_in_files(paths, old, new, dry_run=False)` | Replace text across files.            |
| `watch_dir(path, on_event, recursive=False)`       | Subscribe to best-effort file events. |

## Related

* [Filesystem guide](../../filesystem)
* [Uploads](../../filesystem/uploads)
* [Downloads](../../filesystem/downloads)