> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# File Commands

> Upload, download, update, and delete durable files.

Upload, download, update, and delete durable files.

Output formatting flags (`--json`, `--jq`, and `--template`) are documented once in [Output Formatting](/cli/output) and are omitted from the tables below.

## `bctrl file list`

List files

```bash
bctrl file list [flags]
```

| Flag                    | Description                                         |
| ----------------------- | --------------------------------------------------- |
| `--space <id>`          | Filter by space id                                  |
| `--run <id>`            | Filter by run id                                    |
| `--runtime <id>`        | Filter by runtime id                                |
| `--type <type...>`      | Filter by file artifact type                        |
| `--source <source>`     | Filter by file source                               |
| `--prefix <path>`       | Filter by path prefix                               |
| `--folders`             | Directory view: direct files plus subfolder rollups |
| `--created-after <iso>` | Only files created after this timestamp             |
| `--q <text>`            | Search query                                        |
| `-L, --limit <number>`  | Maximum number of results to return                 |
| `--cursor <cursor>`     | Pagination cursor                                   |

## `bctrl file get`

View file metadata

```bash
bctrl file get <fileId>
```

## `bctrl file upload`

Upload a file

```bash
bctrl file upload <path> [flags]
```

| Flag                   | Description                                 |
| ---------------------- | ------------------------------------------- |
| `--space <id>`         | Space id; omitted uses caller default space |
| `--path <storagePath>` | Storage path                                |
| `--name <name>`        | Display name                                |
| `--metadata <json>`    | Metadata as inline JSON                     |

## `bctrl file download`

Download file content

```bash
bctrl file download <id> [flags]
```

| Flag          | Description                  |
| ------------- | ---------------------------- |
| `--to <path>` | Output path, or - for stdout |

## `bctrl file patch`

Edit file metadata

```bash
bctrl file patch <fileId> [flags]
```

| Flag                     | Description        |
| ------------------------ | ------------------ |
| `--name <name>`          | Display name       |
| `--metadata-file <path>` | Metadata JSON file |

## `bctrl file delete`

Delete a file

```bash
bctrl file delete <fileId> [flags]
```

| Flag        | Description      |
| ----------- | ---------------- |
| `-y, --yes` | Confirm deletion |