> ## Documentation Index > Fetch the complete documentation index at: https://docs.surfacearea.ai/llms.txt > Use this file to discover all available pages before exploring further. # gateway files > Upload, list, download, move and delete files in the project's drive from the terminal, fetch a URL into it, sync its connectors, and use drive: as an input or output of any worlds data command. `gateway files` is the project's file drive: the same store the dashboard's Files tab, the REST routes under `/api/public/files` and the MCP tools (`list_files`, `get_file`, `request_file_upload`, `confirm_file_upload`, `delete_file`, `move_file`, `create_folder`) use. Files are addressed by path, e.g. `corpora/2026/train.jsonl`. A `drive:` prefix on a path is accepted and ignored. Bytes move directly between your machine and storage over presigned URLs. The platform keeps the index. Each command below is one REST route; the exit codes are the CLI's usual ones: `0` done, `1` the platform refused or a transfer failed, `2` bad arguments or missing credentials. ## Upload ```bash theme={null} gateway files upload rows.json # -> drive:rows.json gateway files upload rows.json --to seeds/ # -> drive:seeds/rows.json gateway files upload rows.json --to seeds/acme.json # -> drive:seeds/acme.json (one file, a full path) gateway files upload ./corpus --to in # a directory recurses: drive:in/corpus/ ``` | Flag | What it does | | - | - | | `--to` | Drive folder to put the files under (default the root). With exactly one file, a `--to` ending in a file name is that file's full path. | | `--content-type` | MIME type recorded for every uploaded file. Default: from the extension (`.jsonl` is `application/x-ndjson`), else `application/octet-stream`. | | `--overwrite` | Replace a file already at the same path. Without it, a taken path is refused. | | `--json` | Print `{ uploaded: [...], refused: [...] }` instead of one line per file. | Each file is three requests: `POST /files` returns a presigned PUT URL; the bytes stream to it with the SHA-256 the platform signed; `POST /files/confirm` marks the file ready. A failed PUT is confirmed with `ok=false`, so no placeholder is left behind. Files starting with `.` are skipped when a directory is walked. Empty files are refused. One refused file does not stop the others; the exit code is `1` when any was refused. Progress prints on standard error on a TTY, or when `GATEWAY_PROGRESS=1`. ## List and read ```bash theme={null} gateway files list # the root: folders, then files gateway files list seeds --json # the platform's listing as JSON gateway files get seeds/rows.json # metadata and a time-limited download URL gateway files download seeds/rows.json --out ./rows.json gateway files cat seeds/rows.json | jq . ``` | Command | Route | Output | | - | - | - | | `list [path] [--page N] [--json]` | `GET /files?prefix=&page=&limit=200` | One line per sub-folder (`name/`), then per file: path, size, type, uploader, modified time. `--page` is 0-based. | | `get ` | `GET /files/download?path=` | `{ path, url, urlExpiry, sizeBytes, contentType, sha256 }`. | | `download [--out]` | the same, then a GET from `url` | Streams to `--out`, default the file's own name in the working directory. | | `cat ` | the same | The bytes on standard output. | ## Organize ```bash theme={null} gateway files mkdir corpora/2026 gateway files move seeds/rows.json corpora/2026/rows.json gateway files move corpora archive # a whole folder gateway files delete archive # a folder and everything under it ``` `move` is metadata only; no bytes are copied. `delete` removes the stored bytes too. Both print how many entries changed and exit `1` naming the path when nothing was there. ## Fetch a URL into the drive ```bash theme={null} gateway files fetch https://example.com/products.csv --to imports/products.csv ``` The bytes pass through your machine, then upload as above. The response's `Content-Type` is recorded unless `--content-type` says otherwise. `--overwrite` replaces a file at that path. The MCP tool `download_url_to_drive` does the same fetch on the platform. ## Connectors A connector is a saved sync from an external connection (a Slack channel, a Google Drive file, an http URL) into a drive folder. Humans create them on the Connectors tab; only connectors with agent access turned on are visible here. ```bash theme={null} gateway files connectors list # id, name, kind, target folder, last sync gateway files connectors sync # run it now; the result lists the landed files ``` Routes: `GET /files/connectors` and `POST /files/connectors/sync { connectorId }`. A connector without agent access is refused with `400`. ## The drive in worlds data commands Every `gateway worlds data` input that takes a local file takes `drive:`; the file is downloaded to a scratch copy, the command runs unchanged, and the report names the drive path under `inputs`. ```bash theme={null} gateway files upload rows.json --to seeds/acme/rows.json gateway worlds data import acme drive:seeds/acme/rows.json gateway worlds data check acme drive:seeds/acme/rows.json gateway worlds data extract acme drive:exports/tools.json --shape tool-results --entity users --to rows/users.jsonl gateway worlds data ingest acme --from drive:calls/tools.jsonl --transform shape.py gateway worlds data calls pull --from drive:queries/tools.json --to calls/tools.jsonl ``` | Command | Drive input | Drive output | | - | - | - | | `worlds data import`, `check` | `drive:` among the rows files | — | | `worlds data extract` | `drive:` as the source | `--to ` | | `worlds data ingest` | `drive:` among the inputs; `--from drive:` reads tool-call records from that file | — | | `worlds data calls pull` | `drive:` among the saved results; `--from drive:` reads a saved ClickHouse result from that file | `--to `; `` may then be omitted | | `worlds session export` | — | `--to ` | | `traces export` | — | `drive:` as `` | `--to` takes `drive:` or a bare path, overwrites, and works beside a local output. The manifest under `.gateway/imports/` records the drive spelling, so `--resume` matches the same import. ## From code TypeScript: `import { files } from "@withgateway/sdk"` (or `@withgateway/sdk/files`) — `uploadFile`, `uploadBytes`, `listFiles`, `iterateFiles`, `getFile`, `readFile`, `downloadFile`, `deleteFile`, `moveFile`, `createFolder`, `listFileConnectors`, `syncFileConnector`. Python: `from gatewaysdk.files import FilesClient` — `upload`, `upload_bytes`, `list`, `iter_files`, `get`, `read`, `download`, `delete`, `move`, `mkdir`, `connectors`, `sync_connector`. Both read `GATEWAY_HOST`, `GATEWAY_PUBLIC_KEY` and `GATEWAY_SECRET_KEY`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.