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

# file

> List, read, write, upload, download, and version workspace files.

```text theme={null}
kylon workspace file — kylon workspace help detail

file — files visible to you
  kylon workspace file list [--room <name_or_id|all|current>] [--directory <prefix>] [--query <keyword>] [--type image|pdf|doc|html]
    Lists files with their IDs, names, types, and sizes.
    IMPORTANT: omit --room to search the current room only. Use --room all
            for workspace-wide file search across all visible rooms, or a
            specific room name/ID to search one room.
    --directory: filter to files whose storage path starts with the prefix.
    --query: case-insensitive substring match on file name.
    --type: MIME-type bucket — image (image/*), pdf (application/pdf),
            doc (text/plain, text/markdown, Word, RTF), html (text/html).
    Use file IDs with attachment fields in Database App records.
  kylon workspace file get --file <file_id>
    Read file metadata and a ready-to-run download command.
  kylon workspace file url --file <file_id> [--variant original|thumbnail]
    Print a temporary signed URL. Prefer file download unless a URL is explicitly needed.
  kylon workspace file download --file <file_id> [--output <path> | --dir <directory>] [--variant original|thumbnail] [--force]
    Download the original file or thumbnail to local disk. Default directory is current working directory.
    Without --force, explicit --output refuses to overwrite an existing path.
  kylon workspace file upload --source <local_path> --dest </workspace/shared/...|/workspace/rooms/{room_id}/...>
    Upload a local file as a versioned shared or room workspace file.
    If the file presents external research, the Source Link Policy applies inside the file itself, not only in the reply that links it: Cover every externally sourced claim, quote, figure, and table row with its own exact source link, placed on the claim or row it supports. A root, homepage, or profile link does not cite the individual items under it, and a detached source list does not cite an otherwise unlinked claim.
    To deliver the file in your reply, pass the returned file id to
    `kylon gateway attach --file <file_id>`. Do not paste a signed URL from
    `file url` into a message — it expires and the image breaks.
    The same file id goes to `thread create`/`thread msg` via
    `--file-ids <file_id,...>` to attach it inside a thread instead.
  kylon workspace file read --path </workspace/...>
    Read a text workspace file by path.
  kylon workspace file write --path </workspace/...> --content <text>
    Write a text workspace file by path.
    If the file presents external research, the Source Link Policy applies inside the file itself, not only in the reply that links it: Cover every externally sourced claim, quote, figure, and table row with its own exact source link, placed on the claim or row it supports. A root, homepage, or profile link does not cite the individual items under it, and a detached source list does not cite an otherwise unlinked claim.

  kylon workspace file delete <file_id>
    Delete a room file. Only the file creator or a room admin can delete.
    Creates a deleted tombstone version and removes the current object; older
    content versions remain available for file version get / file revert.
  kylon workspace file versions --file <file_id>
    List version history for a file. The current version is marked.
  kylon workspace file version get --file <file_id> --version <version_number>
    Read metadata and text content for one version. Binary versions return a signed URL.
    Deleted tombstone versions have no content; revert to an older content version to restore.
  kylon workspace file revert --file <file_id> --to-version <version_number> --expected-current-version <version_number>
    Revert by copying an older version into a new current version. The expected
    current version is required to avoid overwriting newer changes.
Resource link handoff:
- Emit identified Kylon resources as clickable, path-only markdown links with human-readable labels.
- Copy command-returned links verbatim. Otherwise substitute known IDs into the relevant format below; do not guess a path.
- File: `[name](/preview/workspaces/{workspaceId}/files/{fileId}?room={roomId})` when room-scoped, or `[name](/preview/workspaces/{workspaceId}/files/{fileId})` for workspace-scoped and agent-private published files. Prefer a tool-returned link when available.

Note: quote flag values that contain spaces; follow each command's JSON syntax.
```