Writing Commands and Adding Functionality

CopyQ allows you to extend its functionality through commands in following ways.

1. Add custom commands to context menu for selected items in history.
2. Run custom commands automatically when clipboard changes.
3. 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 or
• 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 / 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.

In Menu

If enabled, the command can be run from main window either with application shortcut, from context menu or "Item" menu. The command can be also run from tray menu.

Shortcuts can be assigned by clicking on the button next to the option. These shortcuts work only when CopyQ window has focus.

If the command is run from tray menu, it is applied on clipboard data, otherwise it's applied on data in selected items.

Global Shortcut

If enabled, the command is triggered whenever assigned shortcut is pressed. These shortcuts work even when CopyQ window doesn't have focus.

This command is not applied on data in clipboard nor selected items.

Group: Match Items

This group is visible only for "Automatic" or "In Menu" commands. Sub-options specify when the command can be used.

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://).

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).

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.

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 %1 means text of the selected item or clipboard),
• input for command interpreter (prefixed with bash:, powershell:, python: etc.) or
• 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.

Copy to tab

Creates new item in given tab.

Remove Item

Removes selected items. If enabled for "Automatic" command, the clipboard will be ignored and no other automatic commands will be executed.

Group: Menu Action

This group is visible only for "In Menu" commands.

Hide main window after activation

If enabled, main window will be hidden after the command is executed.

Group: Command options

This group is visible only for "Automatic" or "In Menu" commands.

Wait

Show action dialog before applying options below.

Transform

Modify selected items - i.e. remove them and replace with standard output of the command.

Output

Format of standard output to save as new item.

Separator

Separator for splitting output to multiple items (\n to split lines).

Output tab

Tab for saving the output of command.

Save and Share Commands

You can back up or share commands by saving them in a file ("Save Selected Commands..." button) or by copying them to clipboard.

The saved commands can be loaded back to command list ("Load Commands..." button) or pasted to the list from clipboard.

You can try some examples by copying commands from Command Examples.