Skip to content
Sup

sup.fs

The sup.fs package provides file storage access for the current chat, with support for cross-chat reads using absolute paths.

sup.chat.fs exposes the same methods but is limited to the current chat only.

Files written through this API always belong to the current chat. Reads respect access control.

Example sup.fs Usage
// Save a generated image for reuse later in the chat
const avatar = sup.ai.image.create('pixel art frog avatar');
sup.fs.write('/avatars/frog.png', avatar);


// List saved files
const files = sup.fs.list('/avatars');


// Read one back
const image = sup.fs.read('/avatars/frog.png');
return image;

Methods

sup.fs.exists()

(path: string) → boolean

if (sup.fs.exists('/notes/today.txt')) {
  return 'notes file exists';
}

Checks whether a file or directory exists at the given path.

sup.fs.list()

(path?: string) → { filename?: string; isDirectory: boolean; mimeType?: string; path: string; size?: number; type: "file" | "directory"; url?: string }[]

const root = sup.fs.list();
const avatars = sup.fs.list('/avatars');

Lists files and directories at the given path. When path is omitted, it lists the current chat’s root storage directory.

Each returned item includes:

  • path: Full path within the chat file store
  • type: "file" or "directory"
  • isDirectory: Convenience boolean
  • filename: File name when present
  • mimeType: MIME type for files when known
  • size: File size in bytes when known
  • url: Resolved URL for downloadable files when available

sup.fs.mkdir()

(path: string) → void

sup.fs.mkdir('/exports');
sup.fs.mkdir('/avatars');

Creates an empty directory in the current chat’s file store.

sup.fs.move()

(oldPath: string, newPath: string) → void

sup.fs.move('/drafts/cover.png', '/published/cover.png');

Moves a file to a new path within the current chat.

sup.fs.read()

(path: string) → SupImage | SupAudio | SupVideo | SupFile

const screenshot = sup.fs.read('/images/receipt.png');
return screenshot;

Reads a file and returns the appropriate Sup media object.

This throws if the file does not exist or the current patch does not have access to it.

sup.fs.stat()

(path: string) → null | { filename: string; isDirectory: false; mimeType: string; path: string; size: number; url: string }

const info = sup.fs.stat('/exports/report.pdf');
if (!info) return 'Missing report';


return `${info.filename} is ${info.size} bytes`;

Returns metadata for a file, or null if it does not exist or is not accessible.

sup.fs.write()

(path: string, file: string | SupImage | SupAudio | SupVideo | SupFile, options?: { mimeType?: string }) → SupImage | SupAudio | SupVideo | SupFile

const report = sup.file('https://example.com/report.json', 'application/json');
sup.fs.write('/reports/latest.json', report);


sup.fs.write('/reports/backup.json', 'https://example.com/report.json', {
  mimeType: 'application/json'
});

Writes a file into the current chat’s file store and returns the saved Sup file object.

You can write:

  • URL strings
  • SupImage
  • SupAudio
  • SupVideo
  • SupFile

When writing a URL string, provide options.mimeType if you need a specific content type.

When cross-chat access is enabled for the current patch context, you can read from another chat with an absolute path such as /sup/#03fer8dv70jah614p86zpc3ix/images/avatar.png.

Notes

  • sup.fs supports cross-chat reads with absolute /sup/#[chatId]/path paths when the current chat type allows it.
  • sup.chat.fs is always limited to the current chat.
  • Writes are only allowed for the current chat.