Skip to main content

Clipboard Management

Store, organize, and retrieve clipboard content.

Supported Content Types​

mahpastes handles these content types:

TypeExamplesHow It's Displayed
ImagesPNG, JPG, GIF, WebP, BMP, TIFF, SVGThumbnail preview
VideosMP4, WebM, and other browser-supported codecsFrame thumbnail and lightbox playback
TextPlain text, notesText preview (first 500 characters)
CodeAny programming languageMonospace text preview
JSONAPI responses, configsFormatted JSON preview
HTMLWeb page snippetsHTML source preview
FilesAny file typeFilename with type icon

Adding Clips​

Paste from Clipboard​

The main way to add content:

  1. Copy something to your system clipboard (from any app)
  2. Focus the mahpastes window
  3. 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):

OptionBehavior
Ask which one I meantPrompt each time (default)
Keep the path as textAlways store the path as a text clip; never read the file
Add the file it points toAlways 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.

OptionBehavior
Keep the plain textStore the plain-text flavour (default)
Save the formatting as an HTML clipStore 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:

  1. Select one or more files in Finder/Explorer
  2. Drag them onto the mahpastes window
  3. 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.txt imports 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.exe or 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. open starts 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).

Window focus

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:

  1. Press Win+R, type shell:sendto and press Enter. The Send To folder opens.
  2. In another Explorer window, right-drag mahpastes.exe into that folder and choose Create shortcuts here. Rename the shortcut to mahpastes.

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).

GNOME on Wayland

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​

Clips display in a grid:

  • Large thumbnails for images
  • Text previews for text-based content
  • Metadata showing filename, type, and timestamp

Gallery view

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:

ShortcutAction
EscClose lightbox (closes open menus first)
Arrow LeftPrevious image
Arrow RightNext image
Cmd/Ctrl + CCopy image contents to clipboard

Image lightbox

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 to gio 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 /Applications to 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 .desktop file (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/applications and /var/lib/snapd/desktop/applications; type a path with Ctrl+L to reach them. The app is started with gio launch, falling back to gtk-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, or x-special/gnome-copied-files on 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.FileManager1 service, 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.

Temporary Files

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​

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 filtering

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:

  1. Click the menu button (three dots) on a clip
  2. Select Archive
  3. The clip moves to the Archive view
  4. Access archived clips via the Archive button

Archived clips:

  • Don't appear in the main gallery
  • Can be unarchived at any time
warning

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:

  1. Click the menu button (three dots) on a clip
  2. Select Delete
  3. 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 popover

Sort FieldDescription
Date addedCreation timestamp (default, newest first)
FilenameAlphabetical by filename
File sizeClip data size in bytes
Content typeMIME 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.