Automate Your Workflow with CopyQ Scripts and CommandsCopyQ is an advanced clipboard manager that stores and organizes clipboard history, supports images and formatted text, and — crucially — provides a powerful scripting and command system that lets you automate repetitive tasks and integrate clipboard actions into your workflow. This article walks through the concepts, practical examples, and best practices to help you automate common tasks with CopyQ scripts and commands.
What makes CopyQ’s automation powerful
- Scriptable with JavaScript and shell commands. CopyQ supports JavaScript-like scripts (QtScript) and lets you run arbitrary shell commands, combining clipboard data with system utilities.
- Flexible triggers and commands. Commands can be executed manually, via keyboard shortcuts, from the tray menu, or automatically in response to clipboard events.
- Item properties and search. Each clipboard item has metadata (title, notes, custom fields) searchable and usable in scripts.
- Cross-platform. Works on Linux, Windows, and macOS (with some variations), so automation can be reused across systems.
Key concepts
- Clipboard item: a stored entry in CopyQ (text, HTML, image, binary).
- Command: a configured action that can modify items, run scripts, interact with the clipboard, or call external programs.
- Script: small program run by a command. CopyQ supports QtScript (ECMAScript/JavaScript-like) and can invoke shell commands via utils.exec or similar.
- Tab: logical group of items; scripts and commands can interact with specific tabs.
- Shortcut/trigger: a keyboard or event that runs a command.
Getting started: basic commands
Open CopyQ preferences → Commands to add new commands. A command has:
- Name — shown in menu and used to find it.
- Command — the script or shell line executed.
- In menu — whether it appears in tray menu.
- Global shortcut — optional key to run it.
- When — conditions for execution (e.g., on clipboard change).
Example: a simple command to paste the last text item (shell approach for Linux/X11):
copyq read 0 | xdotool type --clearmodifiers --file - Or use CopyQ’s internal functions in a script to set clipboard and simulate paste:
// Paste last text item by setting clipboard and sending keys var text = read(0, "text"); setClipboard(text); paste(); // built-in function: simulate Ctrl+V (behavior depends on platform) Useful scripting functions
Commonly used built-in functions and utilities in CopyQ scripts:
- read(index, format) — returns item content in a format (e.g., “text”, “html”, “image”).
- write(text) — write a new item.
- remove(index) — remove item.
- pop() / push() — stack-style operations.
- select(index) — make item active.
- set(index, data, format) — set item data.
- get(index, “property”) / set(index, “property”, value) — item metadata.
- count() — number of items.
- tabs() / tab() — list and access tabs.
- utils.exec(command) — execute shell command and return output.
- showMenu(menu_items) — display a menu and return selection.
- clipboard() / setClipboard(data[, format]) — get/set clipboard.
- paste() — simulate paste (may require proper permissions or platform support).
Example automations
Below are practical scripts/commands you can add to CopyQ to automate everyday tasks. Paste each into a new command in the Commands preferences and assign shortcuts or triggers as needed.
- Clean and normalize copied text
Removes extra whitespace, converts smart quotes to straight quotes, and normalizes newlines.
// Clean text: normalize whitespace and quotes var i = 0; var text = read(i, "text"); if (!text) exit(); text = text.replace(/ /g, " ").replace(/“|”|„/g, '"').replace(/‘|’/g, "'"); text = text.replace(/[ ]+ /g, " ").replace(/ {3,}/g, " "); setClipboard(text); paste(); - Strip formatting (paste plain text)
Useful when copying from rich sources and pasting into plain-text editors or forms.
Shell variant (Linux/macOS):
copyq read 0 text | copyq write 0 text/plain && copyq select 0 && paste JavaScript variant:
var text = read(0, "text") || read(0, "plain"); if (!text) exit(); setClipboard(text); paste(); - Save clipboard images to a folder with timestamp
Automatically save image items to ~/Pictures/Clipboard (create folder first) and copy path to clipboard.
var img = read(0, "image"); if (!img) exit(); var now = new Date(); var name = sprintf("clipboard_%04d%02d%02d_%02d%02d%02d.png", now.getFullYear(), now.getMonth()+1, now.getDate(), now.getHours(), now.getMinutes(), now.getSeconds()); var folder = "/home/USERNAME/Pictures/Clipboard"; // change for your system var path = folder + "/" + name; utils.save(img, path); setClipboard(path); notice("Saved image to: " + path); (Replace /home/USERNAME with your path; on Windows use “C:/Users/You/Pictures/Clipboard\” and adjust separators.)
- Quick templates/snippets menu
Create a command that shows a menu of frequently used text snippets and pastes the selected one.
var items = ["Email: [email protected]", "Address: 123 Main St", "Thanks, —Your Name"]; var sel = showMenu(items); if (sel < 0) exit(); setClipboard(items[sel]); paste(); - Append timestamp and send to a log file
When you copy something, append it with a timestamp to a plaintext log.
var txt = read(0, "text"); if (!txt) exit(); var now = new Date(); var line = sprintf("[%04d-%02d-%02d %02d:%02d:%02d] %s ", now.getFullYear(), now.getMonth()+1, now.getDate(), now.getHours(), now.getMinutes(), now.getSeconds(), txt); utils.exec("bash -c 'mkdir -p ~/Documents/clipboard_logs; printf %s " + JSON.stringify(line) + " >> ~/Documents/clipboard_logs/clipboard.log'"); Automating on events
Use the command “When” conditions to run scripts automatically when the clipboard changes or when an item is added to a specific tab. Typical uses:
- Auto-clean text when copied from browsers.
- Auto-save images.
- Auto-run OCR on copied screenshots (call tesseract via utils.exec).
Example: Run OCR on new image clipboard items (Linux example using tesseract):
if (!hasFormat(0, "image")) exit(); var tmp = "/tmp/copyq_clip.png"; utils.save(read(0, "image"), tmp); var out = utils.exec("tesseract " + tmp + " - -l eng"); if (out) { write(out); notice("OCR result added to clipboard history"); } Set When to “Clipboard changed” to trigger automatically.
Integrating external tools
CopyQ works well with system tools. Examples:
- xdotool/xdg-open on Linux to paste or open items.
- tesseract for OCR.
- pandoc for converting clipboard HTML to Markdown.
- git/shell scripts to quickly save snippets to a repo.
Example: Convert HTML clipboard to Markdown using pandoc:
var html = read(0, "text/html"); if (!html) exit(); var p = utils.exec("pandoc -f html -t markdown", html); if (!p) exit(); write(p); setClipboard(p); paste(); Note: utils.exec can accept input for many platforms; check CopyQ docs or test on your OS.
Managing complexity: good practices
- Test scripts with a small data set before enabling automatic triggers.
- Use tabs to separate types of items (e.g., “Images”, “Snippets”, “To OCR”).
- Add clear names and descriptions to commands; include a global shortcut for frequently used actions.
- Keep backups of important scripts (store them in a Git repo).
- Use filtering (hasFormat, search) to limit when scripts run.
Troubleshooting tips
- If paste() doesn’t work reliably, simulate paste with platform-specific tools (xdotool,osascript, AutoHotkey).
- Permission issues: scripts that call external programs may require PATH adjustments or full paths.
- On Windows, adjust path separators and use PowerShell or cmd syntax when needed.
- Use notice(“message”) or print() inside scripts for debugging.
Example workflow setups
- Research workflow: Auto-strip formatting + save sources to a “Research” tab, tag items with source URLs, and run a command to bulk export to Markdown.
- Developer workflow: Save code snippets into a “Snippets” tab, run a command to wrap snippets with boilerplate, and push to a snippets repo.
- Image-heavy workflow: Auto-save screenshots to a folder, run OCR, and paste recognized text into an editor.
Security considerations
- Scripts can run arbitrary commands. Avoid running untrusted scripts.
- Be careful when automatically executing clipboard content — it may contain malicious payloads like commands or URLs.
- Use conditions (hasFormat, search) to prevent inappropriate executions.
Where to learn more
- CopyQ’s built-in help and command editor include many examples.
- The CopyQ GitHub repository and community issues often show real-world scripts and patterns.
- Experiment: small scripts + shortcuts let you iterate quickly.
Automating with CopyQ scales from tiny conveniences (strip formatting, paste snippets) to complex pipelines (OCR, file storage, content conversion). Start with a few simple commands, store them in a versioned place, and progressively combine them into larger workflows as needs grow.
Leave a Reply