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 under Settings > API.

export MP_API_KEY=mp_your_key_here

Add this line to your shell profile (~/.zshrc or ~/.bashrc) so it persists across sessions.

Verify

Confirm the CLI can reach the API:

mp api status

Expected output:

Connected to mahpastes API at http://localhost:44557

Environment Variables

Variable	Required	Default	Description
MP_API_KEY	Yes	--	API key starting with mp_
MP_API_URL	No	http://localhost:44557	API base URL

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 (requires --filename):

echo "meeting notes" | mp clip upload --filename notes.txt

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

Downloading Clips

Stream raw clip data to a file:

mp clip data 42 > output.png

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

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

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)
3	Authentication error (invalid or revoked key)

Use exit codes in scripts:

mp api status > /dev/null 2>&1
if [ $? -ne 0 ]; then
  echo "mahpastes is not reachable or key is invalid"
fi

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

• Clipboard Management -- feature reference
• Watch Folders -- watch folder details
• Troubleshooting -- CLI error solutions