CLI Automation
Use the mp command-line tool to manage clips, tags, and backups from your terminal. All operations go through the mahpastes REST API -- the desktop app must be running.
Setup
Install
Build and install the binary:
make mp-install
By default this installs mp into a user-writable bin directory:
- macOS/Linux:
~/.local/binunlessGOBINis set - Windows:
GOBIN, then%GOPATH%\bin, then%USERPROFILE%\go\bin
If ~/.local/bin is not in your PATH, add it in your shell profile:
export PATH="$HOME/.local/bin:$PATH"
On Windows, make sure the resolved install directory is in your PATH.
If you prefer a different install directory, run:
make mp-install MP_INSTALL_DIR=/usr/local/bin
Configure
Set your API key as an environment variable. Create a key in the desktop app (menu drawer > API) — or, once you already hold an admin key, with mp api key create.
export MP_API_KEY=mp_your_key_here
Add this line to your shell profile (~/.zshrc or ~/.bashrc) so it persists across sessions.
To keep the key out of your shell profile, save it to a file only you can read and point MP_API_KEY_FILE at it instead:
(umask 077 && printf '%s\n' 'mp_your_key_here' > ~/.config/mahpastes-key)
export MP_API_KEY_FILE=~/.config/mahpastes-key
The file must hold just the key (a trailing newline is fine). MP_API_KEY wins when both are set.
The desktop app's API server is off until you start it. Turn on Start on launch in the API modal so it starts with the app (see REST API).
Verify
Confirm the CLI can reach the API and that your key is accepted:
mp api status
Expected output:
Connected to mahpastes API at http://localhost:44557
Shell completion and man pages are installed with make mp-install; see Shell Completion. Every command and flag is listed in the CLI Reference.
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
MP_API_KEY | Yes* | -- | API key starting with mp_ |
MP_API_KEY_FILE | No | -- | Path to a file holding just the key; used when MP_API_KEY is unset |
MP_API_URL | No | http://localhost:44557 | API base URL |
MAHPASTES_API_KEY | No | -- | Fallback for MP_API_KEY, used only when MP_API_KEY is unset (the name the Claude Code plugin uses) |
MAHPASTES_API_URL | No | -- | Fallback for MP_API_URL, used only when MP_API_URL is unset |
MP_TIMEOUT | No | 30s | How long to wait for the connection and for the server to start responding (e.g. 10s or 10). It never limits the transfer itself, so large uploads and downloads are not cut off, and commands that wait on long server-side work only use it for the connection (backup create/restore, maintenance, dedup all, plugin install/update/run, watch process, clip download of several clips). On expiry mp exits with code 2 |
* One of MP_API_KEY or MP_API_KEY_FILE is required.
Uploading Files
Upload a single file:
mp clip upload photo.png
Upload with a tag:
mp clip upload photo.png --tag screenshots
Upload multiple files at once:
mp clip upload *.png --tag batch
Upload from stdin. Without --filename the clip is named paste-<timestamp>.<ext>, with the extension sniffed from the content (.txt for text, .png, .pdf, .gz and so on for known binary types, .bin otherwise; --content-type picks the extension instead). - as the file argument means stdin too. Empty input is an error rather than an empty clip, and mp clip upload with no arguments on an interactive terminal stops with an error instead of waiting for input (pass - to type the clip instead, ending it with Ctrl-D, or Ctrl-Z then Enter on Windows):
echo "meeting notes" | mp clip upload
echo "meeting notes" | mp clip upload --filename notes.txt
some-command | mp clip upload - --tag logs
Use -q/--quiet on upload and list to print only bare clip IDs, one per line, for capturing in scripts:
id=$(echo hi | mp clip upload -q)
mp clip list --tag logs -q | mp clip delete --stdin
If any file in a multi-file upload fails (or cannot be tagged or given its expiration), mp clip upload still prints the clips that did upload and then exits with code 1.
Upload with an expiration:
mp clip upload temp.txt --expire 30m
Duration formats: 30m (minutes), 2h (hours), 7d (days), 1d12h (combined).
Listing and Filtering
List recent clips:
mp clip list
Filter by tag:
mp clip list --tag work --limit 10
Search by filename or content:
mp clip list --search report
Filter by content type:
mp clip list --content-type image/png
Show archived clips:
mp clip list --tag old-project --archived
Paginate through results:
mp clip list --limit 20 --offset 40
Sort by created_at (the default), name, size or type, in desc (the default) or asc order. Unknown values are rejected:
mp clip list --sort size --dir desc --limit 5
Downloading Clips
Stream raw clip data to a file:
mp clip data 42 > output.png
Print the newest non-archived clip, optionally within a tag, like pbpaste:
mp clip data --latest
mp clip data --latest --tag notes | wc -l
When stdout is a terminal, mp clip data refuses binary content (an image, an archive) instead of dumping it onto the screen. Redirect the output, or pass --force to write it anyway.
Download with the original filename:
mp clip download 42
Download to a specific path:
mp clip download 42 -o ~/Downloads/photo.png
Download multiple clips as a ZIP:
mp clip download 1 2 3 -o clips.zip
Opening Clips
Open a clip in the application your system uses for its file type:
mp clip open 42
Or name the application (open -a on macOS; on Linux and Windows the program is run with the file):
mp clip open 42 --app Preview
mp clip open 42 --app gimp
mp clip open downloads the clip into a private folder under your user cache directory
(mahpastes/mp-open, for example ~/.cache/mahpastes/mp-open on Linux) and opens that copy. The copy
is left there because the application reads it after mp has exited; delete the folder whenever you
like. Editing the copy does not change the clip. This works against the desktop app and against
mahpastesd, as long as the clip's data can be downloaded to this computer.
Programs, scripts and installers (.exe, .bat, .ps1, .py, .sh, .msi, .command, .pkg,
.desktop and similar) are not opened with the default application, since that could run them; use
mp clip download instead, or name a program with --app.
To show the clip in the mahpastes window instead, use its clip link:
mp clip open 42 --in-app
Bulk Operations
Delete multiple clips by ID:
mp clip delete 1 2 3
Pipe IDs from another command:
mp clip list --tag temp --json | jq -r '.clips[].id' | mp clip delete --stdin
Archive in bulk:
mp clip archive 10 11 12
Set expiration on multiple clips:
mp clip expire 5 6 7 --duration 7d
Bulk commands accept --stdin to read one ID per line from stdin. This pairs well with jq and other pipeline tools.
Renaming and Unarchiving
Rename a clip:
mp clip rename 42 new-name.png
Unarchive clips:
mp clip unarchive 42
mp clip unarchive 1 2 3
Clip Metadata
Each clip can have arbitrary key-value metadata:
mp clip metadata list 42
mp clip metadata get 42 author
mp clip metadata set 42 author "John Doe"
mp clip metadata delete 42 author
Tag Management
Create a tag (parent tags are created automatically):
mp tag create work/projects
Assign a tag to a clip:
mp tag assign 42 --tag work
Assign a tag to multiple clips:
mp tag assign 1 2 3 --tag work/client1
Remove a tag from a clip:
mp tag remove 42 --tag work
List all tags:
mp tag list
List children of a tag:
mp tag list --children-of work
List clips with a specific tag:
mp tag clips photos --limit 20
Update a tag's name or color:
mp tag update photos --name "my photos" --color "#00ff00"
Delete a tag:
mp tag delete photos
View or set hidden tags:
mp tag hidden
mp tag hidden --set "1,2,3"
Watch Folders
Add a watch folder for images:
mp watch add ~/Screenshots --filter presets --presets images
Add a folder with auto-tagging:
mp watch add ~/Downloads --auto-tag downloads
List configured watch folders:
mp watch list
Pause and resume:
mp watch pause 1
mp watch resume 1
Pause all folders globally:
mp watch pause --global
Check watch system status:
mp watch status
Update a watch folder's settings:
mp watch update 1 --filter presets --presets images,videos
Remove a watch folder:
mp watch remove 1
Process existing files in a watch folder:
mp watch process 1
Deduplication
List groups of duplicate clips:
mp dedup list
Merge duplicates for a specific clip (keeps the specified clip, removes others):
mp dedup merge 42
Remove all duplicates across the library:
mp dedup all
Plugins
List installed plugins:
mp plugin list
Install, enable, disable, or remove:
mp plugin install https://example.com/my-plugin.lua
mp plugin enable 1
mp plugin disable 1
mp plugin remove 1
Run a plugin action:
mp plugin run 1 process-image --clip 42 --option quality=high
Check for updates or update a specific plugin:
mp plugin update --check
mp plugin update 1
Manage plugin storage:
mp plugin storage list 1
mp plugin storage get 1 api_key
mp plugin storage set 1 api_key sk-12345
Tag Serving
Start an HTTP server for a tag's clips:
mp serve start my-site --port 8080 --api-access readwrite
List running servers:
mp serve list
Stop a server:
mp serve stop my-site
Clipboard
Copy clip contents or a file reference to the system clipboard (requires the desktop app):
mp clipboard copy 42
mp clipboard copy-file 42
API Keys
Manage the keys the CLI itself authenticates with. All three commands need an admin key in MP_API_KEY.
Create a key:
mp api key create "CI pipeline"
The plaintext key is printed once, under key, and cannot be retrieved afterwards — only its hash is stored. The "save this key" reminder is written to stderr, so it never pollutes piped output; with --json the full result is emitted as JSON and can be read straight off:
export MP_API_KEY=$(mp api key create ci --role editor --json | jq -r .key)
| Flag | Default | Description |
|---|---|---|
--role | viewer | viewer, editor, or admin |
--scoped-tag | 0 (unscoped) | Tag ID to confine the key to (not a tag name) |
mp api key create deploy-bot --role editor --scoped-tag 3
An admin key can mint further keys of any role, scoped or not — key management is not confined by tag scope. Hand out viewer or editor keys for delegated access, and keep admin keys to yourself.
List keys:
mp api key list
ID NAME ROLE PREFIX SCOPE STATUS
7 CI pipeline editor mp_a1b2... work/client1 active
4 old-laptop viewer mp_9f8e... revoked 2026-07-24 08:15:02
Revoked keys stay listed for 7 days after revocation and are then deleted; STATUS shows when the clock started. Raw keys are never shown — PREFIX is the first 8 characters.
Revoke a key by ID:
mp api key revoke 4
Revoking takes effect on the next request. A key that does not exist, or was already revoked, exits non-zero.
Backups
Create a backup:
mp backup create ~/backups/mahpastes-$(date +%Y%m%d).zip
Pipe a backup to cloud storage:
mp backup create - | aws s3 cp - s3://bucket/mahpastes-backup.zip
Restore from a backup:
mp backup restore ~/backups/mahpastes-20260313.zip
JSON Output
Every command supports --json for machine-readable output:
mp clip list --json | jq '.clips[].id'
mp tag list --json | jq '.[] | select(.count > 10)'
mp clip get 42 --json | jq '.filename'
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Connection error (API unreachable or not responding within MP_TIMEOUT) |
| 3 | Authentication error (missing, invalid or revoked key) |
mp --version prints the CLI version; send it along with bug reports.
Use exit codes in scripts:
mp api status > /dev/null 2>&1
case $? in
0) ;;
2) echo "mahpastes is not running or its API is disabled" ;;
3) echo "MP_API_KEY is missing, invalid or revoked" ;;
*) echo "mp api status failed" ;;
esac
Example: Daily Backup Script
#!/bin/bash
set -e
BACKUP_DIR="$HOME/backups/mahpastes"
mkdir -p "$BACKUP_DIR"
FILENAME="mahpastes-$(date +%Y%m%d-%H%M%S).zip"
mp backup create "$BACKUP_DIR/$FILENAME"
# Keep only the last 7 backups
ls -t "$BACKUP_DIR"/mahpastes-*.zip | tail -n +8 | xargs rm -f
echo "Backup saved: $FILENAME"
Related
- Integration Recipes -- wire
mpinto fzf, tmux, vim, git, file managers and macOS Quick Actions - Clipboard Management -- feature reference
- Watch Folders -- watch folder details
- Troubleshooting -- CLI error solutions