---
title: "file | Speedscale Docs"
description: "Read local or user-defined files with Speedscale to extract small data items like secrets or configurations for your API testing and mocking needs"
canonical: "https://docs.speedscale.com/guides/transformation/extractors/file/"
---

[Documentation index](https://docs.speedscale.com/guides/llms.txt) | [Markdown](https://docs.speedscale.com/guides/transformation/extractors/file/index.md) | [Canonical page](https://docs.speedscale.com/guides/transformation/extractors/file/)

# file

<a id="purpose"></a>

### Purpose

**file** reads the entire contents of a file from the local file system or in a user defined document. This transform can only be used on the generator and responder. Typically this extractor is used to pull small amounts of data like a secret or configuration item, or from [user data](https://docs.speedscale.com/reference/glossary/#user-data).

<a id="usage"></a>

### Usage

```json
"type": "file",
"config": {
    "filename": "<path to file>"
}
```

*   **filename** - the location of the file. Speedscale recognizes three forms:
    *   an absolute path on the local file system (e.g. `/var/secrets/myssecret.key`). A local path is read only where the replay runs. A transform preview in the dashboard shows `will be loaded at runtime` instead, and a runtime variable that reads a local path cannot be previewed in Speedscale cloud.
    *   `s3://<name>` to pull from [user data](https://docs.speedscale.com/reference/glossary/#user-data) in the Speedscale cloud
    *   `dataframe:<key>` — a **portable** reference that resolves to user data in the cloud and to a local workspace file under `proxymock/dataframes/` when proxymock runs the replay. Use this form whenever you want the same transform to work in both environments without editing the filename.

<a id="examples"></a>

### Examples

Pull from a file on the local file system:

```json
"type": "file",
"config": {
    "filename": "/var/secrets/myssecret.key"
}
```

Pull from user data in the Speedscale cloud. The `s3://` prefix indicates that the file is [user data](https://docs.speedscale.com/reference/glossary/#user-data).

```json
"type": "file",
"config": {
    "filename": "s3://values.csv"
}
```

Pull from a portable dataframe reference. The `dataframe:` prefix lets the same blueprint or transform work in both local proxymock replays and cloud replays — proxymock looks under `proxymock/dataframes/<id>/<file>` and the cloud resolves the same key under user data.

```json
"type": "file",
"config": {
    "filename": "dataframe:my-dataframe__values.csv"
}
```

The `__` separator stands in for a path separator in the underlying workspace layout (e.g. `my-dataframe/values.csv`). This is what `proxymock cloud push snapshot` writes when it migrates absolute filenames to the portable form, and what `proxymock automation` workflows emit out of the box.
