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

Command	Requires Server	Description
dms cl copy [text]	No	Copy text to clipboard (reads stdin if no arg)
dms cl paste	No	Paste clipboard contents to stdout
dms cl watch [cmd]	No	Watch clipboard changes, optionally pipe to command
dms cl history	Yes	List clipboard history with previews
dms cl get <id>	Yes	Get full entry data by ID
dms cl delete <id>	Yes	Delete history entry by ID
dms cl clear	Yes	Clear all clipboard history
dms cl search [query]	Yes	Search history with filters
dms cl config get	Yes	Get current config
dms cl config set	Yes	Update config options

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

Field	Type	Default	Description
disabled	bool	false	Disable clipboard manager entirely
disableHistory	bool	false	Don't persist clipboard to database
maxHistory	int	100	Max entries to keep in history
maxEntrySize	int	10485760	Max single entry size in bytes (10MB)
autoClearDays	int	0	Auto-delete entries older than N days (0 = disabled)
clearAtStartup	bool	false	Clear history when server starts

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.

Method	Params	Description
clipboard.getHistory	none	Get all history entries
clipboard.getEntry	{id: uint64}	Get entry by ID
clipboard.deleteEntry	{id: uint64}	Delete entry by ID
clipboard.clearHistory	none	Clear all history
clipboard.search	{query?, limit?, offset?, mimeType?, isImage?}	Search history
clipboard.getConfig	none	Get current config
clipboard.setConfig	config fields	Update config

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