Skip to main content

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/bin unless GOBIN is 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​

VariableRequiredDefaultDescription
MP_API_KEYYes*--API key starting with mp_
MP_API_KEY_FILENo--Path to a file holding just the key; used when MP_API_KEY is unset
MP_API_URLNohttp://localhost:44557API base URL
MAHPASTES_API_KEYNo--Fallback for MP_API_KEY, used only when MP_API_KEY is unset (the name the Claude Code plugin uses)
MAHPASTES_API_URLNo--Fallback for MP_API_URL, used only when MP_API_URL is unset
MP_TIMEOUTNo30sHow 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
tip

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
note

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)
FlagDefaultDescription
--roleviewerviewer, editor, or admin
--scoped-tag0 (unscoped)Tag ID to confine the key to (not a tag name)
mp api key create deploy-bot --role editor --scoped-tag 3
warning

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​

CodeMeaning
0Success
1General error
2Connection error (API unreachable or not responding within MP_TIMEOUT)
3Authentication 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"