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

# rb.file

> Read and write files in the script's own folder and its data folder.

`rb.file` reads and writes files in the script's directory and in its data
folder. A script reaches for it to keep settings, state, logs, and recordings
between runs.

This script counts its runs in a JSON file in its data folder and appends a
line to a log beside it:

```luau theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
-- rebind: min_sdk=3.13.0 name=example version=1.0.0
local path = "@data/state.json"
local state = { runs = 0 }
if rb.file.exists(path) then
  state = rb.file.read_json(path)
end

state.runs += 1
rb.file.write_json(path, state)
rb.file.append("@data/runs.log", "run " .. state.runs .. "\n")
rb.log.info("run", state.runs, "saved in", rb.file.data_dir())
```

Paths are relative to the script's directory. An absolute path raises
`Absolute paths are not allowed`; a path containing `..` or one that leaves
the directory raises `Path traversal detected`.

A path starting with `@data/`, or `@data` alone, reaches the script's data
folder instead; it needs `min_sdk=3.13.0`. There is one data folder for each
package or standalone script, kept outside the scripts folder under
`script-data` in Rebind's data folder, and created when first used. The same
path rules apply inside it. `rebind script data <path>` prints where it is.

A marketplace update, a move, or a rename keeps the data folder. A new script, a
copy, a script moved into or out of a package, and an install that replaces a
same-named file or package Rebind cannot verify as the same source start with an
empty folder; data left behind by a replaced install is moved to
`script-data/.displaced`, not deleted. Deleting the script or package in Rebind
deletes its data folder. Cloud backups, the scripts folder, and shared
packages leave it out, so it suits recordings, logs, and other data a script
collects.

`rb.file.rmdir("@data")` raises, though what is inside can be removed. A script
with no file, such as a scratchpad, has no data folder: `@data` paths raise,
and `exists`, `is_dir`, and `is_file` return `false`. Sound files for
`rb.audio.play`, needles for `rb.screen.find_image`, and `rb.config` paths
accept `@data/` paths too.

| Signature | Returns |
| - | - |
| `rb.file.read(path: string) -> string` | UTF-8 text |
| `rb.file.read_bytes(path: string) -> string` | raw bytes |
| `rb.file.write(path: string, content: string) -> ()` | overwrites; any bytes |
| `rb.file.append(path: string, content: string) -> ()` | appends, creating the file |
| `rb.file.exists(path: string) -> boolean` | `false` also for a path containing `..` or outside the directory |
| `rb.file.delete(path: string) -> boolean` | `false` when the path is not a file |
| `rb.file.list(path: string?) -> { string }` | names in a directory; the script directory when omitted |
| `rb.file.mkdir(path: string) -> boolean` | creates it and missing parents |
| `rb.file.rmdir(path: string) -> boolean` | removes it recursively; raises when it cannot |
| `rb.file.copy(src: string, dst: string) -> ()` | |
| `rb.file.move(src: string, dst: string) -> ()` | a rename; may fail across file systems |
| `rb.file.read_json(path: string) -> any` | parsed JSON |
| `rb.file.write_json(path: string, value: any) -> ()` | pretty-printed JSON |
| `rb.file.script_dir() -> string` | absolute path of the script directory |
| `rb.file.data_dir() -> string` | absolute path of the script's data folder; raises for a script with no file; `min_sdk` 3.13.0 |
| `rb.file.size(path: string) -> number` | bytes |
| `rb.file.time(path: string) -> number` | last modified, Unix seconds |
| `rb.file.is_dir(path: string) -> boolean` | never raises |
| `rb.file.is_file(path: string) -> boolean` | never raises |

Other failures raise the operating system's message.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.