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

# Manage Files

> Read, write, upload, download, search, replace, and watch machine files from the CLI.

Use `nullspace machine file ...` for file operations inside a running machine.
Use `nullspace machine upload ...` for local file and directory transfers.

## Read And Write

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine file read mch_123 /workspace/app.py
nullspace machine file read mch_123 /workspace/archive.bin --encoding base64 --json
printf "hello\n" | nullspace machine file write mch_123 /workspace/hello.txt
printf 'Zm9vCg==' | nullspace machine file write mch_123 /workspace/foo.txt --encoding base64
```

Batch write small in-memory files with JSON or `@file.json`:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine file write-files mch_123 '[["/workspace/a.txt","a\n"],["/workspace/b.txt","b\n"]]'
nullspace machine file write-files mch_123 @files.json
```

Most machine file commands accept `--user` when the path should be resolved as a
specific machine user.

## List And Inspect

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine file list mch_123 /workspace --depth 1 --json
nullspace machine file exists mch_123 /workspace/hello.txt
nullspace machine file info mch_123 /workspace/hello.txt
```

`exists` exits with status `0` when the path exists and `1` when it does not, so
it works naturally in shell scripts.

## Move, Permissions, And Delete

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine file mkdir mch_123 /workspace/archive
nullspace machine file mv mch_123 /workspace/hello.txt /workspace/archive/hello.txt
nullspace machine file chmod mch_123 /workspace/archive/hello.txt 0644
nullspace machine file rm mch_123 /workspace/archive/hello.txt
```

## Upload Local Files

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine upload mch_123 ./dist/app.tar.gz /workspace/app.tar.gz
nullspace machine upload mch_123 ./src /workspace/src --exclude '*.pyc'
nullspace machine upload mch_123 - /tmp/stdin.bin
```

Large files can use resumable transfer, checksums, and concurrent parts:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine upload mch_123 ./large.bin /data/large.bin \
  --resumable always \
  --checksum auto \
  --concurrency 4
```

If an upload fails after creating a resumable session, retry with the reported
upload ID:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine upload mch_123 ./large.bin /data/large.bin --resume upload_123
```

Directory uploads support conflict policies and dry runs:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine upload mch_123 ./src /workspace/src --conflict merge --dry-run
```

## Signed URLs

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine file upload-url mch_123 /workspace/input.bin
nullspace machine file download-url mch_123 /workspace/result.tar.gz
```

Use signed URLs when a browser, CI job, or another service should transfer bytes
directly instead of proxying through your local CLI process.

## Search, Replace, And Watch

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine file find mch_123 /workspace "TODO"
nullspace machine file search mch_123 /workspace "*.py"
nullspace machine file replace mch_123 old_name new_name /workspace/app.py /workspace/lib.py
nullspace machine file watch mch_123 /workspace --recursive --timeout 30
```

`find` searches file contents. `search` matches file names. `watch` streams file
events as JSON lines until interrupted or until `--timeout` expires.

## Related

* [Filesystem](../filesystem)
* [Uploads](../filesystem/uploads)
* [Downloads](../filesystem/downloads)
* [CLI Reference](../reference/cli)