Writing Commands and Adding Functionality
CopyQ allows you to extend its functionality through commands in following ways:
Add custom commands to context menu for selected items in history.
Run custom commands automatically when clipboard changes.
Assign global/system-wide shortcuts to custom commands.
Here are some examples what can be achieved by using commands:
Automatically store web links or other types of clipboard content in special tabs to keep the history clean.
Paste current date and time or modified clipboard on a global shortcut.
Pass selected items or clipboard to external application (e.g. web browser or image editor).
Keep TODO lists and tag items as „important“ or use custom tags.
See Command Examples for some other ideas and useful commands.
Command Dialog
You can create new commands in Command dialog. To open the dialog either:
Press default shortcut F6.
Select menu item „Commands/Global Shortcuts…“ in „File“ menu.
Command dialog contains:
list of custom commands on the left
settings for currently selected command on the right
command filter text field at the top
buttons to modify the command list (add, remove and move commands) at the top
buttons to save, load, copy and paste commands at the bottom
Create New Command
To create new command click the „Add“ button in Command dialog. This opens list with predefined commands.
„New Command“ creates new empty command (but it won’t do anything without being configured). One of the most frequently used predefined command is „Show/hide main window“ which allows you to assign global shortcut for showing and hiding CopyQ window.
If you double click a predefined command (or select one or multiple commands and click OK) it will be added to list of commands. The right part of the Command dialog now shows the configuration for the new command.
For example, for the „Show/hide main window“ you’ll most likely need to change only the „Global Shortcut“ option so click on the button next to it and press the shortcut you want to assign.
Commands can be quickly disabled by clicking the check box next to them in command list.
By clicking on „OK“ or „Apply“ button in the dialog all commands will be saved permanently.
Command Options
The following options can be set for commands.
If unsure what an option does, hover mouse pointer over it and tool tip with description will appear.
Name
Name of the command. This is used in context menu if „In Menu“ check box
is enabled. Use the pipe character | in the name to create sub-menus.
Group: Type of Action
This group sets the main type of the command. Usually only one sub-option is set.
Automatic
If enabled, the command is triggered whenever clipboard changes.
Automatic items are run in order they appear in the command list. No
other automatic commands will be run if a triggered automatic command
has „Remove Item“ option set or calls copyq ignore.
The command is applied on current clipboard data - i.e. options below access text or other data in clipboard.
Global Shortcut
Global or system shortcut is a keyboard shortcut that works even if the main application window is not focused.
If enabled, the command is triggered whenever assigned shortcut is pressed.
This command is not applied on data in clipboard nor selected items.
Script
If enabled, the command is script which is loaded before any other script is started. This allows overriding existing functions and creating new ones (allowing new command line arguments to be used).
See Script Commands.
Display
If enabled, the command is used to modify item data before displaying. Use
data() to retrieve current item data and setData() to modify the data
to display (these are not stored permanently).
See Display Commands.
Group: Match Items
This group is visible only for „Automatic“ or „In Menu“ commands. Sub-options specify when the command can be used.
1. Content
Regular expression to match text of selected items (for „In Menu“ command) or clipboard (for „Automatic“ command).
For example, ^https?:// will match simple web addresses (text
starting with http:// or https://).
2. Window
Regular expression to match window title of active window (only for „Automatic“ command).
For example, - Chromium$ or Mozilla Firefox$ to match some web
browser window titles ($ in the expression means end of the title).
3. Filter
A command for validating text of selected items (for „In Menu“ command) or clipboard (for „Automatic“ command).
If the command exits with non-zero exit code it won’t be shown in context menu and automatically triggered on clipboard change.
Example, copyq: if (tab().indexOf("Web") == -1) fail() triggers the
command only if tab „Web“ is available.
4. Format
Match format of selected items or clipboard.
The data of this format will be sent to standard input of the command - this doesn’t apply if the command is triggered with global shortcut.
Command
The command to run.
This can contain either:
simple command line (e.g.
copyq popup %1- expression%1means text of the selected item or clipboard)input for command interpreter (prefixed with
bash:,powershell:,python:etc.)CopyQ script (prefixed with
copyq:)
You can use COPYQ environment variable to get path of application
binary.
Current CopyQ session name is stored in COPYQ_SESSION_NAME
environment variable (see Sessions).
Example (call CopyQ from Python):
python:
import os
from subprocess import call
copyq = os.environ['COPYQ']
call([copyq, 'read', '0'])
Example (call CopyQ from PowerShell on Windows):
powershell:
$Item1 = (& "$env:COPYQ" read 0 | Out-String)
echo "First item: $Item1"
Group: Action
This group is visible only for „Automatic“ or „In Menu“ commands.
1. Copy to tab
Creates new item in given tab.
2. Remove Item
Removes selected items. If enabled for „Automatic“ command, the clipboard will be ignored and no other automatic commands will be executed.
Group: Command options
This group is visible only for „Automatic“ or „In Menu“ commands.
1. Wait
Show action dialog before applying options below.
2. Transform
Modify selected items - i.e. remove them and replace with standard output of the command.
3. Output
Format of standard output to save as new item.
4. Separator
Separator for splitting output to multiple items (\n to split
lines).
5. Output tab
Tab for saving the output of command.