Clipboard Manager

██████╗██╗     ██╗██████╗ ██████╗  ██████╗  █████╗ ██████╗ ██████╗
██╔════╝██║     ██║██╔══██╗██╔══██╗██╔═══██╗██╔══██╗██╔══██╗██╔══██╗
██║     ██║     ██║██████╔╝██████╔╝██║   ██║███████║██████╔╝██║  ██║
██║     ██║     ██║██╔═══╝ ██╔══██╗██║   ██║██╔══██║██╔══██╗██║  ██║
╚██████╗███████╗██║██║     ██████╔╝╚██████╔╝██║  ██║██║  ██║██████╔╝
╚═════╝╚══════╝╚═╝╚═╝     ╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝

The dms cl command provides a Wayland clipboard manager with history, search, and other configurable knobs. It uses the ext_data_control_v1 protocol for clipboard access.

Overview​

Quick Start​

# Copy text to clipboard
echo "hello" | dms cl copy
dms cl copy "hello world"

# Paste clipboard contents
dms cl paste

# View clipboard history
dms cl history

# Search history
dms cl search "password"

Commands​

dms cl copy [text]​

Copies data to the Wayland clipboard. Forks a background process by default to serve paste requests.

dms cl copy [text] [flags]

Arguments:

• text (optional): Text to copy. If omitted, reads from stdin.

Flags:

• -d, --download: Download URL to clipboard (see below)
• -f, --foreground: Stay in foreground instead of forking
• -o, --paste-once: Exit after first paste (one-shot copy)
• -t, --type <mime>: MIME type (default: text/plain;charset=utf-8)

Examples:

# Copy string directly
dms cl copy "Hello, world!"

# Copy from stdin
echo "piped content" | dms cl copy

# Copy file contents
dms cl copy < file.txt

# Copy image with MIME type
dms cl copy -t image/png < screenshot.png

# One-shot copy (clipboard cleared after first paste)
dms cl copy -o "temporary secret"

# Download image from URL to clipboard
dms cl copy --download "https://example.com/image.png"

Download Mode​

The --download flag fetches a file from a URL and copies it to the clipboard as text/uri-list. This works with both native apps and sandboxed Flatpaks.

dms cl copy --download "https://example.com/photo.jpg"

How it works:

1. Downloads the URL to ~/.cache/dms/clipboard/
2. Validates the content is an image or video
3. Offers two MIME types to the clipboard:
   • text/uri-list — Native apps read the file directly
   • application/vnd.portal.filetransfer — Flatpaks retrieve via XDG portal

Portal support: When available, the XDG Desktop Portal's FileTransfer interface lets sandboxed Flatpak apps access the downloaded file securely. If the portal isn't running, only native apps will work.

dms cl paste​

Reads current clipboard selection and writes to stdout.

dms cl paste

Examples:

# Paste to terminal
dms cl paste

# Paste to file
dms cl paste > output.txt

# Pipe to another command
dms cl paste | wc -l

dms cl watch [command]​

Watches for clipboard changes. Without arguments, prints changes to stdout.

dms cl watch [command] [flags]

Arguments:

• command (optional): Command to pipe clipboard contents to.

Flags:

• --json: Output as JSON objects
• -s, --store: Store changes to history database (no server needed)

Examples:

# Print clipboard changes to stdout
dms cl watch

# Pipe each clipboard change to a command
dms cl watch notify-send

# Output as JSON
dms cl watch --json

# Store to history without running the server
dms cl watch --store

JSON output format:

{"data": "clipboard content", "mimeType": "text/plain", "timestamp": 1699900000, "size": 17}

dms cl history​

Lists history entries with ID, type, timestamp, and preview. Requires the DMS server.

dms cl history [flags]

Flags:

• --json: Output as JSON array

Example output:

ID       Type        Timestamp            Preview
─────────────────────────────────────────────────────────────
1        text/plain  2024-01-15 10:30:00  Hello, world!
2        image/png   2024-01-15 10:31:00  [image 1920x1080]
3        text/plain  2024-01-15 10:32:00  Some longer text that gets trunca...

dms cl get <id>​

Retrieves full entry data by ID. Outputs raw data by default.

dms cl get <id> [flags]

Arguments:

• id (required): Entry ID from history.

Flags:

• --json: Output full entry as JSON

Examples:

# Get raw data
dms cl get 42

# Get as JSON
dms cl get 42 --json

# Save image to file
dms cl get 42 > image.png

dms cl delete <id>​

Delete a history entry by ID. Requires the DMS server.

dms cl delete <id>

dms cl clear​

Clear all clipboard history. Requires the DMS server.

dms cl clear

dms cl search [query]​

Search history with text matching and filters. Requires the DMS server.

dms cl search [query] [flags]

Arguments:

• query (optional): Text to search for.

Flags:

• -l, --limit <n>: Max results (default: 50, max: 500)
• -o, --offset <n>: Result offset for pagination
• -m, --mime <type>: Filter by MIME type substring
• --images: Only image entries
• --text: Only text entries
• --json: Output as JSON

Examples:

# Search for text
dms cl search "password"

# Find all images
dms cl search --images

# Find text entries containing "http"
dms cl search --text "http"

# Paginate results
dms cl search --limit 10 --offset 20

# Filter by MIME type
dms cl search -m "image/png"

Configuration​

dms cl config get​

Get current clipboard manager configuration as JSON.

dms cl config get

dms cl config set​

Update configuration options.

dms cl config set [flags]

Flags:

• --max-history <n>: Max history entries to keep
• --auto-clear-days <n>: Delete entries older than N days (0 disables)
• --clear-at-startup / --no-clear-at-startup: Clear history on server start
• --disable / --enable: Disable/enable clipboard manager entirely
• --disable-history / --enable-history: Disable/enable history persistence

Examples:

# Set max history to 500 entries
dms cl config set --max-history 500

# Auto-clear entries older than 7 days
dms cl config set --auto-clear-days 7

# Disable history persistence
dms cl config set --disable-history

# Clear history on each startup
dms cl config set --clear-at-startup

Configuration File​

Settings are stored at $XDG_CONFIG_HOME/DankMaterialShell/clsettings.json (defaults to ~/.config/DankMaterialShell/clsettings.json).

Configuration Options​

JSON schema:

{
  "disabled": false,
  "disableHistory": false,
  "maxHistory": 100,
  "maxEntrySize": 10485760,
  "autoClearDays": 0,
  "clearAtStartup": false
}

IPC Methods​

For programmatic access, the clipboard manager exposes JSON-RPC methods over the DMS IPC socket.

Example IPC call:

dms ipc call clipboard.search '{"query": "hello", "limit": 10}'

Command Reference​

dms cl [command] [flags]

Available Commands:

• copy [text]: Copy to clipboard
• paste: Paste from clipboard
• watch [cmd]: Watch clipboard changes
• history: List clipboard history
• get <id>: Get entry by ID
• delete <id>: Delete entry by ID
• clear: Clear all history
• search [query]: Search history
• config get: Get configuration
• config set: Update configuration

Global Flags:

• -c, --config <path>: Specify custom DMS config directory
• -h, --help: Show help