Clipboard Management
Store, organize, and retrieve clipboard content.
Supported Content Types
mahpastes handles these content types:
| Type | Examples | How It's Displayed |
|---|---|---|
| Images | PNG, JPG, GIF, WebP, BMP, TIFF, SVG | Thumbnail preview |
| Videos | MP4, WebM, and other browser-supported codecs | Frame thumbnail and lightbox playback |
| Text | Plain text, notes | Text preview (first 500 characters) |
| Code | Any programming language | Monospace text preview |
| JSON | API responses, configs | Formatted JSON preview |
| HTML | Web page snippets | HTML source preview |
| Files | Any file type | Filename with type icon |
Adding Clips
Paste from Clipboard
The main way to add content:
- Copy something to your system clipboard (from any app)
- Focus the mahpastes window
- Press Cmd/Ctrl + V
mahpastes detects the content type and stores it.
Pasting a File Path
Copying a file as a pathname (Finder's Copy as Pathname, Explorer's Copy as path, or dragging a file into a terminal) puts plain text on the clipboard, which is ambiguous: you may want the path itself, or the file it points to.
When pasted text names a file that exists on this computer, mahpastes asks which one you meant. You can paste several paths at once — one per line — as long as every line resolves to a file. Paths that don't exist, and paths naming a folder or anything that isn't an ordinary file, are pasted as text without a prompt.
Paths mahpastes handed out itself — from Copy Path, or from dragging a clip out of the window — are also pasted as text. Re-importing one would just duplicate the clip you copied it from.
Recognized forms: absolute paths (/Users/me/photo.png, C:\Users\me\photo.png), ~/-relative paths,
file:// URLs, and paths that are quoted or shell-escaped. Relative paths are not resolved.
To skip the prompt, set Settings → Pasted File Paths → On paste (desktop only — a browser session served over the network can't see your filesystem, so pasted paths always stay text there):
| Option | Behavior |
|---|---|
| Ask which one I meant | Prompt each time (default) |
| Keep the path as text | Always store the path as a text clip; never read the file |
| Add the file it points to | Always import the file, prompting only when the path isn't a real file |
Pasting Rich Text
Text copied from a browser, Mail, Notes or a word processor usually reaches the clipboard twice: as plain
text, and as HTML that keeps its links and formatting. By default a paste keeps the plain text, as a
pasted_text_….txt clip.
To keep the formatting instead, set Settings → Rich Text Paste → On paste to Save the formatting as
an HTML clip. A paste that carries HTML is then stored as a pasted_html_….html clip (text/html),
wrapped into a complete UTF-8 page when the clipboard held only a fragment, so it opens correctly in a
browser later. A paste without HTML still becomes a text clip and goes through the pasted-path handling
above (a path copied in Finder or Explorer is plain text only, so it is still offered as a file); a paste
that carries HTML is always saved as HTML. The setting works in the desktop app and in the browser UI.
| Option | Behavior |
|---|---|
| Keep the plain text | Store the plain-text flavour (default) |
| Save the formatting as an HTML clip | Store the HTML flavour whenever the paste has one |
Some editors (VS Code, for example) put syntax-coloured HTML on the clipboard along with the code, so with the second option code pasted from them becomes an HTML clip too.
Drag and Drop
Drop files directly into the app:
- Select one or more files in Finder/Explorer
- Drag them onto the mahpastes window
- Release to import
Supported drop types:
- Single files
- Multiple files at once
Opening Files with mahpastes
mahpastes is a single window per data directory. Launching it again while it is already running does not start a second copy: the running window comes forward instead, and any files named on the command line are imported into it.
That makes these work:
- Command line:
mahpastes photo.png notes.txtimports both files into the running window (or into the window it opens, if mahpastes was not running). Relative paths are resolved against the directory you ran the command from. - Windows: dropping files onto
mahpastes.exeor a shortcut to it, or Send to > mahpastes in Explorer once you have added the shortcut (see Send to on Windows). - Linux: with the desktop entry from
make install(scripts/linux/install.sh), mahpastes is listed under Open With for text, Markdown, images, PDF and JSON files, and dropping files on its launcher imports them. It is never made the default application for any of these types. Launching the app again from the app menu, KRunner or a dock raises the running window. - macOS: Finder Open With > mahpastes works for any file, and so does dropping files on the Dock
icon. mahpastes is listed as an alternative handler only, so it never becomes the default app for a
file type. Starting a second copy from a terminal (
open -n -a mahpastes --args "$PWD/file.png", or running the binary inside the bundle) also hands its files to the running window.openstarts the app in/, so pass absolute paths there.
Opened files go through the same import as a pasted file path: duplicate detection, the upload expiry from the bottom bar and folder auto-tagging all apply, and the archive view switches back to the active list so the new clips are visible. Only ordinary files you can read are imported; folders, missing or unreadable paths and mahpastes' own temporary files (from Copy Path or drag-out) are skipped with a notice. A large selection is imported a few dozen files at a time.
If the running process is the headless server (mahpastesd) rather than the desktop window, the second
launch cannot hand over and shows the "another mahpastes instance is already running" error instead. A
launch while the running window is closing waits a few seconds for it to exit and then starts normally.
The same handover brings back a window that is hidden because Keep running when the window is closed is on or mahpastes started hidden at login (see Background & Startup).
Windows and most desktops bring the window to the front. On Wayland the compositor decides: GNOME may only highlight mahpastes in the taskbar ("needs attention") rather than raise it.
Send to on Windows
Explorer's Send to menu lists the shortcuts in your shell:sendto folder, and passes the selected
files to the program a shortcut points at. The zip release does not add one for you. To add it:
- Press Win+R, type
shell:sendtoand press Enter. The Send To folder opens. - In another Explorer window, right-drag
mahpastes.exeinto that folder and choose Create shortcuts here. Rename the shortcut tomahpastes.
Or run this in PowerShell from the folder that holds mahpastes.exe:
$shell = New-Object -ComObject WScript.Shell
$link = $shell.CreateShortcut("$([Environment]::GetFolderPath('SendTo'))\mahpastes.lnk")
$link.TargetPath = (Resolve-Path .\mahpastes.exe).Path
$link.Save()
Select files in Explorer, right-click, and choose Send to > mahpastes (on Windows 11 it is under
Show more options). The running window imports them; if mahpastes is not running, it starts with them.
Delete the shortcut from shell:sendto to remove the entry. If you move mahpastes.exe, create the
shortcut again.
Explorer passes the selection on a single command line of about 32,000 characters, so a very large selection (thousands of files) is cut short. Use watch folders or the import wizard for those.
Save the Clipboard from a Global Shortcut (Linux)
The Linux desktop entry has a Save Clipboard as Clip action. It saves whatever is on the clipboard as a new clip, exactly as pasting into the window would, even while mahpastes is in the background. Right-click the launcher to run it, or bind it to a key:
- KDE Plasma: System Settings > Keyboard > Shortcuts > Add New > Application..., choose mahpastes, then assign a key to Save Clipboard as Clip.
- GNOME and others: add a custom shortcut whose command is the path of the installed binary with
--paste-clipboard, for example~/.local/bin/mahpastes --paste-clipboard.
The window comes forward so you can see the result. An image on the clipboard is saved as an image; otherwise the text is saved (a copied file path asks whether to import the file, as a paste does).
mahpastes reads the clipboard through XWayland, which GNOME only updates while an X11 window has focus. There, a shortcut pressed right after copying in a Wayland-native app can save the previous clipboard content. KDE Plasma is not affected.
Expiration
Set per-clip expiration when uploading (dropdown in the bottom bar) or on existing clips via the context menu. See Auto-Delete for details.
Viewing Clips
Gallery View
Clips display in a grid:
- Large thumbnails for images
- Text previews for text-based content
- Metadata showing filename, type, and timestamp

Lightbox
Click any image or video clip's preview to open it in a full-screen lightbox. Videos use the native playback controls and load on demand; available codecs depend on your browser or platform WebView.
Navigation:
- Arrow keys or arrow buttons to move between images and videos
- Swipe left/right on trackpad or touchscreen
- Trackpad horizontal scroll with momentum detection
Zoom and pan:
These controls apply to images; videos keep their native playback controls.
- Slider in the bottom bar (1x to 4x)
- Trackpad pinch to zoom
- Touch pinch to zoom
- Double-click to reset zoom to 1x
- Click and drag to pan when zoomed in
Bottom bar:
- Position counter (e.g. "1/5"), filename, and media details
- Zoom slider with percentage display for images
- Actions menu with Open, Open With, Copy (Path / File / Contents, plus Rich Text for HTML clips on macOS), Save, Edit, Tags, Metadata, Rename, Set Expiration / Cancel Expiration, Merge Duplicates (if duplicates exist), Archive, Delete
- Plugin action menu (if plugins define lightbox actions)
Right-clicking the image opens that same Actions menu at the pointer.
Closing:
- Esc closes the lightbox (any open menu closes first)
- Clicking the dark area around the image closes it too
Backdrop clicks only count when they are just that — clicking the image itself, releasing a pan drag over the backdrop, and a click that only dismisses an open menu all leave the viewer open. To disable backdrop closing entirely, turn off Settings → Image Viewer → Click outside image to close. The preference is remembered across restarts.
Keyboard shortcuts:
| Shortcut | Action |
|---|---|
| Esc | Close lightbox (closes open menus first) |
| Arrow Left | Previous image |
| Arrow Right | Next image |
| Cmd/Ctrl + C | Copy image contents to clipboard |

Opening Content
- Images: Click the preview to open in the lightbox
- Videos: Click the frame preview to play in the lightbox
- Text/Code/JSON/HTML: Click the preview to open in the text editor
Content Detection
mahpastes categorizes content by MIME type:
text/plain → Plain text editor
text/html → HTML source view
application/json → Formatted JSON view
image/* → Image viewer/editor
video/* → Video player
Retrieving Clips
Context Menu
Click the three-dot menu button on any clip card, or right-click anywhere on the card, to open the context menu. The menu uses submenus to group related actions. Available actions:
- Open -- opens the clip with the system default application (
xdg-open, falling back togio open, on Linux). On Windows a file type with no registered application shows the "Open with" dialog instead - Open With -- on macOS, a submenu listing the applications registered for the clip's file type, as Finder's Open With does: the default application first, marked (default), then the rest by name. Other… at the bottom opens a file dialog in
/Applicationsto pick any application. The list is looked up when the submenu first opens (on macOS 11 and earlier only the default application is listed); if the lookup fails, only Other… is shown. On Windows, shows the native "Open with" dialog, which lists installed and Microsoft Store apps; ticking Always use this app there makes that app the default for the file type. On Linux it opens a file dialog to choose an application: pick the app's.desktopfile (or switch the filter to All Files to pick a plain executable); the dialog starts in whichever applications directory holds the most apps -- usually/usr/share/applications, or the Flatpak exports on Fedora Atomic and similar. The others are/var/lib/flatpak/exports/share/applications,~/.local/share/flatpak/exports/share/applications,~/.local/share/applicationsand/var/lib/snapd/desktop/applications; type a path with Ctrl+L to reach them. The app is started withgio launch, falling back togtk-launch. A Flatpak app started this way can only read the clip if its sandbox grants access to the mahpastes data folder, where the clip's temporary file lives - Copy (submenu) -- expands to show Path, File, Contents, Link, and, for HTML clips on macOS, Rich Text
- Path -- creates a temporary file and copies the absolute path to clipboard
- File -- copies the clip as a file to the system clipboard (macOS via NSPasteboard, Windows via PowerShell, Linux as
text/uri-list, orx-special/gnome-copied-fileson Cinnamon, MATE, Xfce, Budgie and Pantheon; on Linux the copied file stays on the clipboard only while mahpastes is running) - Contents -- copies raw text or image data to the system clipboard (available for text/*, application/json, and image/* types; non-PNG images are converted to PNG before copying). HTML clips are copied as their source text. On macOS, JPEG, GIF and TIFF images are also offered in their original format alongside the PNG, so apps that accept it keep the original compression or GIF animation; TIFF images are offered in their original format only
- Rich Text (macOS, HTML clips) -- copies the page as formatted text: Mail, Notes, Pages and other rich-text editors paste it with its formatting and links, while plain-text fields receive its readable text rather than the markup
- Link -- copies the clip's
mahpastes://clip/<id>link; opening it shows the clip in mahpastes (see Clip Links)
- Save -- opens a native save dialog to export the clip to disk; in the desktop app the confirmation toast offers Show in folder, which shows the saved file selected in Finder, Explorer, or the Linux file manager (through the
org.freedesktop.FileManager1service, or by opening the containing folder when no file manager provides it). In the browser UI the clip is downloaded instead - Edit -- opens the image editor or text editor (shown for editable types)
- Tags -- opens the tag popover
- Metadata -- opens the metadata modal for viewing and editing key-value pairs
- Rename -- opens a prompt to change the clip's filename
- Set Expiration -- opens expiration preset popover (shown when clip has no expiry)
- Cancel Expiration -- removes expiration (shown when clip has an active expiry)
- Archive / Restore -- toggles archive state
- Merge Duplicates -- merges duplicate clips (shown when duplicates exist)
- Delete -- deletes the clip after confirmation
If plugins define card actions, they appear in a Plugins submenu below a divider.
When more than one clip is selected, right-clicking one of the selected clips opens the bulk actions instead of this menu. See Bulk Actions.
Files created via "Copy Path" are stored in a temp directory and cleaned up periodically (60-minute lease) and when mahpastes exits. Don't rely on them for permanent storage.
Organizing Clips
Search
Filter clips by filename and content type:
- Type in the search bar to filter
- Search is case-insensitive substring matching against the filename and MIME type
- Results update as you type
- Press Enter to move focus to the first visible result
- Filters only the currently visible cards (does not search clip contents)
- Works in both the main gallery and archive views (whichever is active)

Search options
The sliders button inside the search box opens two options that widen a search beyond the cards on screen:
- Search file contents — looks inside text and JSON clips, not just their names. This option is remembered between sessions.
- Show hidden clips — includes clips carrying a hidden tag. Results that only appear because of this are dimmed. The option resets to off each time mahpastes starts, so hidden stays hidden by default.
With either option on, the database searches the whole library rather than only the clips currently loaded in the gallery, then returns the first 50 matches in the selected sort order. The interface does not currently indicate when more matches exist. Both options are unavailable in folder view, where a folder lists one exact tag level.
Archive
Move important clips to a separate space:
- Click the menu button (three dots) on a clip
- Select Archive
- The clip moves to the Archive view
- Access archived clips via the Archive button
Archived clips:
- Don't appear in the main gallery
- Can be unarchived at any time
Archiving does not remove expiration. If a clip has an auto-delete timer, it will still expire even when archived.
Delete
Remove clips you no longer need:
- Click the menu button (three dots) on a clip
- Select Delete
- Confirm the deletion
Deleted clips are permanently removed from the database.
Content Type Details
Images
Supported formats:
- PNG, JPG, JPEG, GIF
- WebP, BMP, TIFF
- SVG (displayed as image)
When pasting from clipboard, images are typically captured as PNG.
Text Content
mahpastes distinguishes between:
- Plain text: Regular text content
- HTML: Content whose trimmed body starts with
<!DOCTYPE html(case-sensitive prefix match) - JSON: Any string that parses as valid JSON
Detection runs at upload time when the incoming content type is text/plain or empty. Files uploaded with an explicit non-text content type keep their original type.
Binary Files
For non-text files:
- Stored as binary blobs
- Displayed with appropriate icons
- Full file preserved for export
Sorting
Control the order of clips in the gallery using the sort popover in the bottom bar.

| Sort Field | Description |
|---|---|
| Date added | Creation timestamp (default, newest first) |
| Filename | Alphabetical by filename |
| File size | Clip data size in bytes |
| Content type | MIME type string |
Click the active sort field to reverse its direction. Click a different field to switch to it: dates start newest first and sizes largest first, filenames and content types from A to Z. The sort button's tooltip names the current sort, and the button is highlighted whenever the sort is not the default (newest first). The sort preference (field and direction) is persisted to the settings table and restored on app launch. A secondary tiebreaker of created_at + id keeps the order stable when two clips share the same value for the primary sort field.
Limits and Performance
- Clip limit: Gallery and deep-search queries return at most 50 clips
- File size: A clip can hold just under 1 GB (a database limit). Files opened with mahpastes (Open With, Send To, the command line) that are larger are skipped with a message. Below that there is no limit, but importing a very large file is slow and briefly uses several times its size in memory
- Preview size: Text previews limited to 500 characters
For large collections, use search and archive to keep the main gallery manageable.
Related
- Drag and Drop -- drag clips out of the app
- Bulk Actions -- operate on multiple clips at once
- Tags -- organize clips with color-coded labels
- Image Editor -- annotate images
- Text Editor -- edit text clips
- Metadata -- attach key-value pairs to clips