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

# fs

> Remote filesystem operations on a sandbox — read, write, upload, download, list, stat, mkdir, rm, mv

## `bonya fs`

Reads and writes files inside a sandbox. Every subcommand names its sandbox by name or id, interchangeably, and omitting it opens a picker:

```shell theme={null}
bonya fs ls web /workspace
bonya fs ls /workspace        # prompts for the sandbox
```

All nine subcommands accept `--by-name` to force name interpretation of the sandbox argument.

## `read` (alias: `cat`)

Prints a remote file to stdout.

```shell theme={null}
bonya fs read [sandbox] <path>
```

```shell theme={null}
bonya fs read web /etc/hostname
bonya fs cat web /etc/hostname
```

## `write`

Writes a local file — or stdin, with `-` — to a remote path.

```shell theme={null}
bonya fs write [sandbox] <path> <local-file-or-->
```

> [!WARNING]
>
> Argument order is **remote path, then local source** — the opposite order from `upload`. `write` exists mainly for piping stdin straight to a remote file; `upload` exists for local-file-to-remote-file with the more intuitive source-then-destination order.

```shell From a local file theme={null}
bonya fs write web /workspace/notes.txt ./notes.txt
```

```shell From stdin theme={null}
echo 'hello' | bonya fs write web /workspace/hello.txt -
```

## `upload`

Uploads a local file to a remote path. Source, then destination — the familiar order.

```shell theme={null}
bonya fs upload [sandbox] <local> <remote>
```

```shell theme={null}
bonya fs upload web ./dist.tar.gz /workspace/dist.tar.gz
```

## `download`

Downloads a remote file to a local path.

```shell theme={null}
bonya fs download [sandbox] <remote> <local>
```

```shell theme={null}
bonya fs download web /workspace/output.log ./output.log
```

## `ls`

Lists a remote directory.

```shell theme={null}
bonya fs ls [sandbox] <path>
```

```shell theme={null}
bonya fs ls web /workspace
```

On a real terminal, `bonya fs ls` looks like this:

## `stat`

Shows metadata (kind, size, mode, modified time) for a remote path.

```shell theme={null}
bonya fs stat [sandbox] <path>
```

```shell theme={null}
bonya fs stat web /workspace/app.py
```

## `mkdir`

Creates a remote directory.

```shell theme={null}
bonya fs mkdir [sandbox] <path>
```

```shell theme={null}
bonya fs mkdir web /workspace/logs
```

## `rm`

Removes a remote file or directory.

```shell theme={null}
bonya fs rm [sandbox] <path> [--recursive]
```

| Flag | Default | Description |
| - | - | - |
| `--recursive` | `false` | Remove directories recursively. |

```shell theme={null}
bonya fs rm web /workspace/tmp.txt
bonya fs rm web /workspace/build --recursive
```

## `mv`

Moves (renames) a remote file or directory.

```shell theme={null}
bonya fs mv [sandbox] <src> <dst>
```

```shell theme={null}
bonya fs mv web /workspace/draft.md /workspace/final.md
```

## All subcommands at a glance

| Command | Arguments | Notes |
| - | - | - |
| `read` (`cat`) | `<path>` | Prints to stdout. |
| `write` | `<path> <local-or-->` | Remote path first, source second. |
| `upload` | `<local> <remote>` | Source first, remote path second. |
| `download` | `<remote> <local>` | |
| `ls` | `<path>` | |
| `stat` | `<path>` | |
| `mkdir` | `<path>` | |
| `rm` | `<path>` | `--recursive` for directories. |
| `mv` | `<src> <dst>` | |


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