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

# Filesystem

> Read, write, list, rename, remove, and manage files inside a Declaw sandbox using sbx.Files.

```go theme={null}
import "github.com/declaw-ai/declaw-go"
```

`sbx.Files` is the `*Filesystem` sub-object available on every `Sandbox` instance. All paths must be absolute paths within the sandbox filesystem.

## `sbx.Files.Read()`

Read a file as a UTF-8 string from the sandbox.

```go theme={null}
content, err := sbx.Files.Read(ctx, "/home/user/script.py")
fmt.Println(content)
```

<ParamField body="path" type="string" required>
  Absolute path inside the sandbox.
</ParamField>

<ParamField body="WithFileUser" type="string" default="server default">
  Unix user context for file operations. Server defaults to `"user"` when not specified.
</ParamField>

**Returns** `(string, error)`

***

## `sbx.Files.ReadBytes()`

Read a file as raw bytes.

```go theme={null}
data, err := sbx.Files.ReadBytes(ctx, "/data/image.png")
```

**Returns** `([]byte, error)`

***

## `sbx.Files.Write()`

Write a UTF-8 string to a file. Creates parent directories automatically.

```go theme={null}
info, err := sbx.Files.Write(ctx, "/home/user/hello.py", "print('hello')")
fmt.Println(info.Path, info.Size)
```

<ParamField body="path" type="string" required>
  Absolute path inside the sandbox.
</ParamField>

<ParamField body="data" type="string" required>
  Content to write.
</ParamField>

**Returns** `(*WriteInfo, error)`

***

## `sbx.Files.WriteBytes()`

Write raw bytes to a file. Uses the binary-safe `PUT /files/raw` endpoint.

```go theme={null}
info, err := sbx.Files.WriteBytes(ctx, "/tmp/blob.bin", rawBytes)
```

**Returns** `(*WriteInfo, error)`

***

## `sbx.Files.WriteFiles()`

Write multiple files in a single batch request. More efficient than calling `Write()` in a loop.

```go theme={null}
err := sbx.Files.WriteFiles(ctx, []declaw.WriteEntry{
    {Path: "/home/user/main.py", Data: "import sys\nprint(sys.argv)"},
    {Path: "/home/user/data.json", Data: `{"key": "value"}`},
})
```

Each entry's `Data` must be a `string`. Use `WriteBytes` for binary data.

<ParamField body="entries" type="[]WriteEntry" required>
  List of `WriteEntry` values. Each has `Path` (string) and `Data` (string).
</ParamField>

**Returns** `error`

***

## `sbx.Files.List()`

List the contents of a directory.

```go theme={null}
entries, err := sbx.Files.List(ctx, "/home/user")
for _, e := range entries {
    fmt.Println(e.Type, e.Path, e.Size)
}
```

<ParamField body="path" type="string" required>
  Absolute path to the directory.
</ParamField>

**Returns** `([]EntryInfo, error)`

***

## `sbx.Files.Exists()`

Check whether a file or directory exists.

```go theme={null}
exists, err := sbx.Files.Exists(ctx, "/home/user/output.csv")
if exists {
    content, _ := sbx.Files.Read(ctx, "/home/user/output.csv")
    fmt.Println(content)
}
```

**Returns** `(bool, error)`

***

## `sbx.Files.GetInfo()`

Get metadata about a single file or directory.

```go theme={null}
info, err := sbx.Files.GetInfo(ctx, "/home/user/script.py")
fmt.Println(info.Path, info.Type, info.Size)
```

**Returns** `(*EntryInfo, error)`

***

## `sbx.Files.Remove()`

Remove a file or directory.

```go theme={null}
err := sbx.Files.Remove(ctx, "/home/user/temp_output.txt")
```

**Returns** `error`

***

## `sbx.Files.Rename()`

Rename or move a file or directory.

```go theme={null}
err := sbx.Files.Rename(ctx, "/home/user/draft.py", "/home/user/final.py")
```

**Returns** `error`

***

## `sbx.Files.MakeDir()`

Create a directory (including parent directories if needed).

```go theme={null}
err := sbx.Files.MakeDir(ctx, "/home/user/output/results")
```

**Returns** `error`

***

## `sbx.Files.Watch()`

<Note>
  Not yet implemented. Returns an error until server-side streaming support is available.
</Note>

Watch a path for filesystem changes. Will return a `*WatchHandle` with an events channel.

***

## Data models

### `EntryInfo`

```go theme={null}
type EntryInfo struct {
    Path string
    Type FileType
    Size int64
}
```

### `FileType`

```go theme={null}
const (
    FileTypeFile      FileType = "file"
    FileTypeDirectory FileType = "dir"
    FileTypeSymlink   FileType = "symlink"
    FileTypeOther     FileType = "other"
)
```

### `WriteInfo`

```go theme={null}
type WriteInfo struct {
    Path string
    Size int64
}
```

### `WriteEntry`

```go theme={null}
type WriteEntry struct {
    Path string
    Data interface{} // must be string for WriteFiles
}
```

***

## Examples

### Upload and execute a script

```go theme={null}
_, err := sbx.Files.Write(ctx, "/home/user/analyze.py", scriptContent)
if err != nil {
    log.Fatal(err)
}
result, err := sbx.Commands.Run(ctx, "python3 /home/user/analyze.py")
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Stdout)
```

### Batch upload files

```go theme={null}
err := sbx.Files.WriteFiles(ctx, []declaw.WriteEntry{
    {Path: "/data/config.json", Data: `{"batch_size": 32}`},
    {Path: "/data/input.csv", Data: csvContent},
})
if err != nil {
    log.Fatal(err)
}
```

### Download generated output

```go theme={null}
_, _ = sbx.Commands.Run(ctx, `python3 -c "open('/tmp/out.csv','w').write('a,b\n1,2')"`)
content, err := sbx.Files.Read(ctx, "/tmp/out.csv")
if err != nil {
    log.Fatal(err)
}
_ = os.WriteFile("local_out.csv", []byte(content), 0644)
```