> ## 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.

# File & directory metadata

> List directories, inspect paths, check existence, search names and contents, and watch volume changes.

Use metadata commands when you need to understand the contents of a persistent
volume without launching a machine.

## List Directories

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  entries = volume.files.list("/datasets")
  for item in entries:
      print(item.path, item.type, item.size)
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace volume ls-files team-data /
  nullspace volume ls-files team-data /datasets
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X GET "${NULLSPACE_API_URL}/v1/volumes/vol_123/files?path=/datasets" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

Direct volume paths are rooted at `/` and do not use machine `cwd`.

## Inspect A Path

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  info = volume.files.info("/datasets/report.txt")
  print(info.path, info.type, info.size, info.modified_at)

  same = volume.files.get_info("/datasets/report.txt")
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace volume info team-data /datasets/report.txt
  nullspace volume stat team-data /datasets/report.txt
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/info" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/datasets/report.txt"}'
  ```
</CodeGroup>

`info` and `stat` both return metadata JSON. `get_info()` is an SDK alias for
`info()`.

## Check Existence

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  if volume.files.exists("/datasets/report.txt"):
      print("present")
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace volume exists team-data /datasets/report.txt
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/exists" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/datasets/report.txt"}'
  ```
</CodeGroup>

The CLI exits with status `0` when the path exists and `1` when it does not.

## Create Directories

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  volume.files.make_dir("/datasets")
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace volume mkdir team-data /datasets
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/mkdir" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/datasets"}'
  ```
</CodeGroup>

## Search Names And Contents

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  content_matches = volume.files.find_files("/datasets", "needle")
  name_matches = volume.files.search_files("/datasets", "*.json")
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace volume find team-data /datasets "needle"
  nullspace volume search team-data /datasets "*.json"
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/find" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/datasets", "pattern": "needle"}'

  curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/search" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/datasets", "pattern": "*.json"}'
  ```
</CodeGroup>

`find` searches file contents. `search` matches file names.

## Watch Changes

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  def on_event(event):
      print(event.type, event.path)

  with volume.files.watch_dir("/datasets", on_event=on_event, recursive=True):
      ...
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace volume watch team-data /datasets --recursive --timeout 30
  ```
</CodeGroup>

Volume watch is not a plain REST call: it streams change events over the volume
data plane rather than a single request/response endpoint, so there is no
`curl` equivalent.

Watches stream JSON events. In multi-host deployments, clients should treat
`resync_required` as a signal to list or stat the watched tree again.

## Related

* [Read & write](./read-write)
* [Upload data](./upload-data)
* [Download data](./download-data)