List Files
vault_list_filesDiscover non-markdown files in an Obsidian vault or folder—images, PDFs, data files—with byte sizes and extension counts to locate and read them.
Instructions
List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.
Example: vault_list_files({}) — every non-markdown file in the vault Example: vault_list_files({ folder: "attachments" }) Example: vault_list_files({ extensions: [".png", ".jpg"], limit: 20 })
When to use: discovering what files exist before reading them with vault_read_file. vault_search, vault_list_notes, and vault_search_by_folder cover only markdown notes, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.
Parameters:
folder: folder path filter (e.g. "attachments" or "Projects/media"), searched recursively; omit for the whole vault
extensions: restrict to these extensions — case-insensitive, with or without the leading dot (".png" and "png" both work)
limit: maximum entries returned (default 50). extension_counts and total always reflect the full filtered set, not just the returned page.
Errors:
A visible folder containing no files — or one that doesn't exist — returns an empty listing, not an error.
A folder path escaping the vault (e.g. "../elsewhere") is rejected with a path-traversal error.
"hidden path blocked" — the folder is hidden (dot-prefixed, like ".obsidian"); hidden folders are not listable, matching Obsidian.
Returns: JSON with files (array of { path, extension, bytes }, sorted by path), extension_counts (per-extension totals over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit). bytes is the on-disk file size, not the delivery cost: reading an image via vault_read_file returns a copy shrunk to fit when needed, so a large listed image is still cheap to read. Text formats return verbatim, so their listed size is what a read delivers. Files of supported types are readable via vault_read_file; vault_search covers markdown notes.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max entries returned (default 50). | |
| folder | No | Folder path to search recursively (e.g. "attachments"). Omit to list the whole vault. | |
| extensions | No | Only include these extensions, case-insensitive, leading dot optional (e.g. [".png", "jpg"]). |