copyq-cli-reference

CopyQ CLI & Scripting Reference

Use this skill whenever the user asks for a CopyQ command, an automation script, or a custom command body. It exists because the agent's training data is unreliable on CopyQ specifics — verify against this reference rather than guessing.

Invocation model

CopyQ has two execution surfaces:

1. Shell CLI — copyq <subcommand> [args...]. Runs against the live CopyQ server (the GUI must be running). Used for one-shot operations, IPC from scripts, and shortcut bindings.
2. Embedded scripting — copyq eval -- '<script>' or a Custom Command's Command body. ECMAScript-style syntax with CopyQ-specific globals. Used for anything stateful or multi-step.

Always check whether the user wants a shell-side command, an eval payload, or a Custom Command — they're not interchangeable.

Core CLI subcommands

Subcommand	Purpose	Example
copyq (no args)	Show/raise main window	copyq
copyq show [TAB]	Show window, optionally focus tab	copyq show "&clipboard"
copyq hide	Hide main window	copyq hide
copyq toggle	Toggle window visibility	copyq toggle
copyq menu [TAB]	Show tray-style item menu	copyq menu
copyq clipboard [MIME]	Read current clipboard	copyq clipboard text/plain
copyq selection [MIME]	Read X11 PRIMARY selection	copyq selection
copyq copy [MIME] DATA	Set clipboard	copyq copy "hello"
copyq copy MIME1 DATA1 MIME2 DATA2	Set multiple MIME types	copyq copy text/plain "x" text/html "<b>x</b>"
copyq paste	Paste current clipboard to focused window	copyq paste
copyq add TEXT...	Add item(s) to current tab	copyq add "first" "second"
copyq write [ROW] MIME DATA...	Write item with explicit MIME	copyq write 0 text/plain "x"
copyq read [MIME] [ROW...]	Read item content	copyq read 0
copyq remove ROW...	Remove items by row	copyq remove 0 1 2
copyq edit [ROW]	Open editor on item	copyq edit 0
copyq separator SEP	Set output separator (default \n)	copyq separator "\t" read 0 1
copyq count	Count items in current tab	copyq count
copyq select ROW	Move item to top	copyq select 3
copyq next / prev	Cycle clipboard through history	copyq next

Tab management

Subcommand	Purpose
copyq tab	List all tabs
copyq tab TAB <subcommand>	Run subcommand against TAB
copyq addTab NAME	Create new tab
copyq removeTab NAME	Remove tab
copyq renameTab OLD NEW	Rename tab

Tab names beginning with & denote keyboard mnemonics (e.g. &clipboard). When passing tab names from shell, quote them.

Scripting language (used in eval and Custom Commands)

ECMAScript-like with CopyQ globals. Key APIs:

// I/O
str(read(0))                           // read item 0 as string
write('text/plain', 'hello')           // write to current tab
add('a', 'b', 'c')                     // append items
remove(0)                              // remove row 0

// Clipboard / selection
clipboard()                            // current clipboard (default text/plain)
clipboard('text/html')                 // specific MIME
copy('hello')                          // set clipboard
copySelection('hello')                 // set PRIMARY selection (X11)
paste()                                // simulate paste in focused window

// Tabs
tab()                                  // current tab name
tab('Notes')                           // switch context to tab "Notes"
tabs()                                 // array of tab names

// Item data (multi-MIME aware)
var d = getitem(0)                     // {mimetype: data, ...}
setitem(0, {'text/plain': 'x'})

// Match / transform helpers
str(data('text/plain'))                // data() = current item being processed
                                       //         in automatic commands
input()                                // stdin (in Custom Commands of type "Command")
print('output')                        // stdout

// UI
popup('title', 'message', timeoutMs)
notification('.title', 'Title', '.message', 'Body')

Automatic commands

Custom commands of type "Automatic" run on every clipboard/selection change. Inside them:

• data(mime) — the data triggering the command.
• dataFormats() — MIME types present.
• Returning false (or calling abort()) stops the chain.
• Calling ignore() makes CopyQ skip storing this item.

Useful patterns

// Skip storing passwords from a known password manager window
if (str(data(mimeWindowTitle)).match(/KeePassXC/))
    ignore();

// Strip formatting on copy
copy(str(data(mimeText)));

// Auto-tag URLs into a "Links" tab
var t = str(data(mimeText));
if (t.match(/^https?:\/\//)) {
    tab('Links');
    add(t);
}

Useful built-in MIME constants

• mimeText — text/plain
• mimeHtml — text/html
• mimeUriList — text/uri-list
• mimeWindowTitle — application/x-copyq-owner-window-title
• mimeItems — serialized item bundle (application/x-copyq-item)

Exit codes

• 0 — success
• 1 — bad arguments
• 2 — connection error (server not running — start with copyq &)
• 3 — script error

Where to look for canonical docs at runtime

If the reference above doesn't cover the API the user needs, fetch the upstream docs:

• Scripting API: https://hluk.github.io/CopyQ/docs/scripting-api
• CLI: https://hluk.github.io/CopyQ/docs/command-line
• Custom commands: https://hluk.github.io/CopyQ/docs/custom-commands

Use WebFetch on those URLs rather than guessing.