WinSCP Free SFTP, FTP and SCP client for Windows
Custom Commands
If there is a remote command you need to execute regularly and in particular if the command works with files, you may find custom commands useful.
A custom command is a predefined command which can contain several patterns that WinSCP replaces, for example, with names of files selected in a panel (see below). For example, the pre-defined custom command Touch, defined as touch “!”, calls the touch command on every selected file in the remote panel.
However you can have even custom commands without patterns, just to avoid typing the command again every time.
Types of Custom Commands
There are basically four types of custom commands:
- Remote or local commands that does not work with files. These can be executed any time.
- Remote commands are executed on the remote servers with the remote files. These commands can modify the files. You need to have selected remote files first to execute the command.
- Local commands are executed on the local machine with the remote files downloaded to temporary folder. It makes no sense for the command to modify the files, because they are not uploaded back after the command finishes. You need to have selected remote files first to execute the command.
- Special type is local command that is executed both with local and remote files. This is particularly useful for running “diff” tools. This type is available only with Commander interface. You can execute such command for set of remote files against the the same number or local files (once for each pair). Another option is to execute it for set of remote files against one local file (once for each remote file) and vice versa.
Patterns Used in Custom Commands
You can use following patterns in your custom commands:
| Pattern | Command Type | Descriptions |
|---|---|---|
!! |
Any | Is replaced with exclamation mark (!). |
! |
Any | Name of file. Command with the pattern will be executed once for every selected file. In general it should be surrounded with quotes for the command to work with filenames containing spaces. Cannot be combined with pattern !&. |
!& |
Any | Quoted, space-delimited list of files. Command with the pattern will be executed only once for all selected files. Cannot be combined with pattern ! and executed recursively. |
!/ |
Any | Current remote path. |
!@ |
Any | Current session hostname. |
!u |
Any | Current session username. |
!p |
Any | Current session password (if remembered). |
!?prompt[\]?default! |
Any | When used, user is prompted to enter value that replaces the pattern. prompt can define a message of the prompt and default a default value, both can be empty. Special characters entered by user are automatically delimited. You can prohibit this using optional backslash (\) before second question mark (?). |
!^! |
Local | Name of local file. In general it should be used in combination with ! or !&. Command with the pattern will be executed once for every selected local file, unless only one local file and several remote files are selected and pattern ! is used. Cannot be executed recursively. |
The custom command is executed for files selected in file panel. It can be optionally executed also for selected directories or for files in selected directories (or both).
Executing and Configuring Custom Commands
Custom commands are located in menu File(s) > Custom Commands, in file context menu and on special Custom Command toolbar. Custom commands can be configured in Preferences.
You may eventually want to execute ad hoc custom command, without predefining it first. To do so, go to File(s) > Custom Commands > Enter. To repeat the last ad hoc custom command, go to File(s) > Custom Commands > Last.
Useful Custom Commands
You can see list of custom commands other users found useful.
