view
App and inputInteract
The app as the user sees it: what the gallery shows and what is selected, Gallery or Reader mode, Quick Look, the main window's panels, shell, size and theme, the Settings and Workflows windows, and Show in Finder. Changes no item and no setting (theme here is for this session only). state reports most of it.
Needs the Interact level or above; hidden from a read-only client.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
action | string one of "show", "select", "mode", "quick_look", "panel", "shell", "theme", "window", "settings", "wait_idle", "reset", "reveal", "workflows" | yes | What to do. show: Change what the gallery shows, as the user would, and read it back: one sidebar row (filter, a folder or a tag), the search, the sort, the thumbnail size. With none of those it only reads. Returns the view and a page of its items, in its order. Choosing a row clears the search, so both together set the row and then search inside it. A folder under Reader shows in Reader mode. (filter, folder, folder_id, linked_id, tag, group, search, sort, thumbnail_size, skip, take) select: Select items in the gallery's view, as clicking them would: ids (replace, the default), add them, remove them, or all. ids [] selects nothing. Every id must be in the view (show first). (ids, how) mode: Switch between the gallery (captures) and Reader mode (bookmarks): the two tabs at the top of the sidebar. Refused in the compact and mini shells and while an editor has unsaved edits. (to) quick_look: Open Quick Look (the spacebar preview) on an item in the view (default the current one) and wait for it to render, or close it with open false. With it open: page shows a page of a PDF or slide deck; zoom (fit, width, actual, or a step in or out) or zoom_percent zooms a still; pan_x / pan_y move a zoomed still; at_ms seeks a video, audio or animated picture and play plays (true) or pauses (false) it. Applied in that order, every value checked against the item before any is; state reports the page, zoom and playback after. (id, path, zoom, zoom_percent, page, pan_x, pan_y, at_ms, play, open) panel: Show or hide a panel of the main window: chat, details (preview, name, tags) or sidebar (library, folders). Not saved to settings. An editor's properties panel is editor panel. (panel, visible) shell: Move the main window between its shells: full (the gallery), compact (capture, edit and share over a strip of the Inbox) or mini (one thumbnail wide). The small ones collapse the gallery, toolbar and title bar. (to) theme: The theme and warmth for this session only, not saved (for staging a picture); settings_set theme / warmth is the user's setting. (theme, warmth) window: Resize the main window, and move it with x and y (global screen points, its top-left corner). (width, height, x, y) settings: Open the Settings window on a tab (or the one it shows), or close it with open false. Its window id is in the result, for screen look. (tab, open) wait_idle: Wait for the app to settle: an editor's load, the last window resize, layout, timeout_ms more for animations, and one rendered frame. Call after editor close, shell, theme and window changes before looking at the screen. (timeout_ms) reset: Put the window in a clean state for a picture: the gallery, panels and Quick Look closed, no search, nothing selected. Changes no item. reveal: Show an item's file (id or path), a folder (folder or folder_id) or a linked folder (linked_id) in Finder, selected, as Show in Finder does. Changes nothing. (id, path, folder, folder_id, linked_id) workflows: Open the Workflows window (the user's saved workflows), or close it with open false. Its window id is in the result, for screen look. Making or changing a workflow stays the user's. (open) |
filter | string one of "all_items", "inbox", "images", "videos", "screen_recordings", "my_recordings", "short_loops", "audio", "documents", "slideshows", "fonts", "bookmarks", "trash", "duplicates", "shared", "unread" | no | show: a sidebar view. |
folder | string | no | show: a folder's rel path from library_find folders ('Reader' is the reader root), or a linked folder's absolute path. reveal: a folder's rel path. |
folder_id | integer | no | show, reveal: a folder by its id from library_find folders, instead of folder. |
linked_id | integer | no | show, reveal: a linked folder by its id from library_find linked, instead of folder. |
group | string | no | show: a Shared Group's page, by its group from share groups. |
tag | string | no | show: the items carrying this tag. |
search | string | no | show: the search bar's text: words, a colour ('#ff0000', '#red') or a type qualifier ('video:'); '' clears it. |
sort | string one of "newest", "oldest" | no | show: newest or oldest first. |
thumbnail_size | integer | no | show: the thumbnails' size in points. |
skip | integer | no | show: items to skip. |
take | integer | no | show: items to return (default 50). |
ids | string[] | no | select: item ids. |
how | string one of "replace", "add", "remove", "all" | no | select: replace (default), add, remove, or all (every item in the view; no ids). |
to | string | no | mode: gallery or reader. shell: full, compact or mini. |
id | string | no | quick_look: the item's id (default the current item). reveal: the item. |
path | string | no | quick_look, reveal: or its path or name. |
zoom | string one of "fit", "width", "actual", "in", "out" | no | quick_look: a still's zoom: a fit, or a step in or out. |
zoom_percent | integer | no | quick_look: a still's zoom in percent of its own pixels (100 is actual size), kept within Quick Look's range; state reports what it took. |
page | integer | no | quick_look: the page of a PDF or slide deck, 1 for the first. |
pan_x | number | no | quick_look: move a still that overflows, in points: positive shows more to the right, negative to the left. |
pan_y | number | no | quick_look: positive shows more below, negative above. |
at_ms | integer | no | quick_look: seek a video, audio or animated picture to this moment, in ms. |
play | boolean | no | quick_look: true plays a video, audio or animated picture, false pauses it. |
open | boolean | no | quick_look, settings, workflows: false closes it (default true). |
panel | string one of "chat", "details", "sidebar" | no | panel: which. |
visible | boolean | no | panel: true shows it, false hides it; omit to toggle. |
theme | string one of "dark", "light", "system" | no | theme: for this session. |
warmth | string one of "cool", "neutral", "warm" | no | theme: the palette's warmth for this session. |
width | integer | no | window: width in points. |
height | integer | no | window: height in points. |
x | integer | no | window: its new left edge in global screen points (give x and y, or neither). |
y | integer | no | window: its new top edge. |
tab | string one of "general", "window", "menu_bar", "capture", "capture_filter", "retina", "recording", "keyboard", "export", "gallery", "browser_extension", "media", "ai_integration", "ai_mcp", "ai_rename", "auto_update", "share_menu", "cloud_sync", "subscription", "privacy" | no | settings: the tab to show. |
timeout_ms | integer | no | wait_idle: settle time for animations on top of the loads (default 500). |
Example
A JSON-RPC call to POST http://localhost:21516/mcp with the bearer token, filling in the required parameters:
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "view", "arguments": { "action": "show" } }}See the MCP server overview for how to connect a client and where the token lives.