This is an old revision of the document!

Scripting and Task Automation

This article contains detailed description of scripting/automation functionality. You may want to see simplified guide to the functionality instead.

In addition to graphical interface, WinSCP offers scripting/console interface with many commands. The commands can be typed in interactively, or read from script file or another source.

Using scripting interface directly is recommended for simple tasks not requiring any control structures. For complex tasks, using WinSCP .NET assembly is preferred.

Using Scripting
Checking Results
Commands
The Console Interface Tool
Verifying the Host Key or Certificate in Script
Running a Script under a Different Account (e.g., Using a Scheduler)
Sharing Configuration with Graphical Mode
Example
Converting Script to Code Based on .NET Assembly
Further Reading

Using Scripting

Enter the console/scripting mode by using winscp.com; or /console command-line parameter with winscp.exe. For details see console/scripting command-line parameters.

For automation, commands can be read from a script file specified by /script switch, passed from the command-line using the /command switch, or read from standard input of winscp.com.

Since WinSCP 5.7, when running commands specified using /script or /command, batch mode is used implicitly and overwrite confirmations are turned off. In older releases and in an interactive scripting mode, the user is prompted in the same way as in GUI mode. To force batch mode (all prompts are automatically answered negatively) use the command option batch abort. For batch mode it is recommended to turn off confirmations using option confirm off to allow overwrites (otherwise the overwrite confirmation prompt would be answered negatively, making overwrites impossible).

Multiple sessions can be opened simultaneously. Use the session command to switch between them.

Note that the first connection to an SSH server requires verification of the host key. Also the first connection to FTPS or WebDAVS host with certificate signed by untrusted authority requires verification of the certificate.

Checking Results

WinSCP executables return exit code 1 when any command is interrupted due to an error or any prompt is answered Abort (even automatically in batch mode). Otherwise it returns the exit code 0.

To further analyze results of scripted operations, you will find XML logging useful.

<?xml version=“1.0” encoding=“UTF-8”?> <!DOCTYPE plist PUBLIC “-AppleDTD PLIST 1.0EN” “http://www.apple.com/DTDs/PropertyList-1.0.dtd”> <plist version=“1.0”> <dict>

key>DeviceClass</key> string>iPad</string> key>DeviceMap</key> array> <dict> <key>BDID</key> <integer>4</integer> <key>BoardConfig</key> <string>k93ap</string> <key>CPID</key> <integer>35136</integer> <key>Platform</key> <string>s5l8940x</string> <key>SCEP</key> <integer>17</integer> </dict> /array> key>FirmwareDirectory</key> string>Firmware</string> key>KernelCachesByPlatform</key> dict/> key>KernelCachesByTarget</key> dict> <key>k93</key> <dict> <key>Release</key> <string>kernelcache.release.k93</string> </dict> /dict> key>MinimumSystemPartition</key> dict> <key>058-00314-002.dmg</key> <integer>1419</integer> /dict> key>ProductBuildVersion</key> string>11D201</string> key>ProductType</key> string>iPad2,1</string> key>ProductVersion</key> string>7.1.1</string> key>RamDisksByPlatform</key> dict> <key>s5l8940x</key> <dict> <key>Update</key> <string>058-00363-002.dmg</string> <key>User</key> <string>058-00183-002.dmg</string> </dict> /dict> key>RestoreRamDisks</key> dict> <key>Update</key> <string>058-00363-002.dmg</string> <key>User</key> <string>058-00183-002.dmg</string> /dict> key>SupportedProductTypeIDs</key> dict> <key>DFU</key> <array> <integer>67144000</integer> </array> <key>Recovery</key> <array> <integer>67144000</integer> </array> /dict> key>SupportedProductTypes</key> array> <string>iPad2,1</string> /array> key>SystemPartitionPadding</key> dict> <key>k93</key> <dict> <key>128</key> <integer>1280</integer> <key>16</key> <integer>160</integer> <key>32</key> <integer>320</integer> <key>64</key> <integer>640</integer> <key>8</key> <integer>80</integer> </dict> /dict> key>SystemRestoreImages</key> dict> <key>User</key> <string>058-00314-002.dmg</string> /dict>

</dict> </plist>

0��0�+� 33�� 0 *�H�� 0{10 UUS10U Apple Inc.1&0$UApple Certification Authority1/0-U&Apple FairPlay Certification Authority0 100210173634Z 150209173634Z0e10 UUS10U Apple Inc.10UApple FairPlay1(0&UiPad.3333AF100210AF0001AF0000090��0 *�H�� 0��$�� (�X��u��3Bd=�+�RlLHDq�h��TT’��r��R鎫վ��x��d �5�sW�?Oצ�i�cƁ��ں��@42��(/Iìm��貖�uϵ(�K��`0^0U��0U�0�0U�2X��B��&�zZhr0U#0�� NI��cbYd0 *�H�� k�E��l�g�%<��L�^ILS�k�o.�y`(�gu#7��a�쑊�� !��“�#l��e�P��Z��H��&�E �jF�yB_ڴ��<�(Q�@��#�C��[�-��0�q0�Y�0 *�H�� 0b10 UUS10U Apple Inc.1&0$UApple Certification Authority10U Apple Root CA0 070214192041Z 120214192041Z0{10 UUS10U Apple Inc.1&0$UApple Certification Authority1/0-U&Apple FairPlay Certification Authority0��0 *�H�� 0��g<]*��w��1��І)� ��dJ�i� ��c�:-!=R�#�)��(�i�r$��x1��*3��H*a��y�]��|�x�R��nr�]ˈ�U��M�O’g��ڭ��0��0U��0U�0�0U� ��NI��cbYd0U#0�+�iG�v ��k�.@��GM^06U/0-0+�)�’�%http://www.apple.com/appleca/root.crl0 *�H�� s��ņu��@�j-�[�n�[�H}@�a-K7p8��K��3o_r��v�WXq�>��.�/�:s�2e V�MxmУtd�T��*�y��I3igA��h��z��$�*�h��{�ٺ�ʓ��7f��1�u��/��97=_��͚p��”��n$i;R��Cp��!�C˻��[��w��MV3]�\Y1��;EVͮ˛��ܓ��Xx�ٙ��^��s4T��0��0��0 *�H�� 0b10 UUS10U Apple Inc.1&0$UApple Certification Authority10U Apple Root CA0 060425214036Z 350209214036Z0b10 UUS10U

Environment Variables

You can use environment variables in the commands, with syntax %NAME%1:

put "%FILE_TO_UPLOAD%"

Note that variable expansion is different than in Windows batch files:

You cannot use any string processing syntax.

You cannot use dynamic/pseudo environment variables, such as %DATE% or %RANDOM%.

References to undefined variables are kept intact (not removed).

You can use %WINSCP_PATH% to refer to WinSCP executable path.

Timestamp

WinSCP automatically resolves %TIMESTAMP% to a real time with format 20141024161712.2

You can customize the format using syntax %TIMESTAMP#format% where format may include yyyy for year, mm for month, dd for day, hh for hour, nn for minute and ss for second. For example %TIMESTAMP#yyyy-mm-dd% resolves to 2014-10-24.3 See other formats you can use.

To use %TIMESTAMP% on command-line in a batch file, you need to escape the % by doubling it to %%TIMESTAMP%%, to avoid batch file interpreter trying to resolve the variable.

This feature is available only in the latest release.

Command	Description
call	Executes arbitrary remote shell command
cd	Changes remote working directory
checksum	Calculates checksum of remote file
chmod	Changes permissions of remote file
close	Closes session
echo	Prints message onto script output
exit	Closes all sessions and terminates the program
get	Downloads file from remote directory to local directory
help	Displays help
keepuptodate	Continuously reflects changes in local directory on remote one
lcd	Changes local working directory
lls	Lists the contents of local directory
ln	Creates remote symbolic link
lpwd	Prints local working directory
ls	Lists the contents of remote directory
mkdir	Creates remote directory
mv	Moves or renames remote file
open	Connects to server
option	Sets or shows value of script options
put	Uploads file from local directory to remote directory
pwd	Prints remote working directory
rm	Removes remote file
rmdir	Removes remote directory
session	Lists connected sessions or selects active session
stat	Retrieves attributes of remote file
synchronize	Synchronizes remote directory with local one

Script Arguments

You can reference script arguments (passed on command-line using parameter /parameter) using syntax %N%, where N is ordinal number of argument1:

put "%1%"

Case Sensitivity of File Names

Note that WinSCP treats filenames in case sensitive manner. So even if your server treats filenames in case insensitive manner, make sure you specify case properly4.

Comments

To insert comments into the script file, start the line with # (hash):

# Connect to the server open mysession

Commands

The following commands are implemented.

To see help for the command, read respective documentation article below or type command help <command> directly in console.

Command Description

call Executes arbitrary remote shell command

cd Changes remote working directory

checksum Calculates checksum of remote file

chmod Changes permissions of remote file

close Closes session

echo Prints message onto script output

exit Closes all sessions and terminates the program

get Downloads file from remote directory to local directory

help Displays help

keepuptodate Continuously reflects changes in local directory on remote one

lcd Changes local working directory

lls Lists the contents of local directory

ln Creates remote symbolic link

lpwd Prints local working directory

ls Lists the contents of remote directory

mkdir Creates remote directory

mv Moves or renames remote file

open Connects to server

option Sets or shows value of script options

put Uploads file from local directory to remote directory

pwd Prints remote working directory

rm Removes remote file

rmdir Removes remote directory

session Lists connected sessions or selects active session

stat Retrieves attributes of remote file

synchronize Synchronizes remote directory with local one

The Console Interface Tool

Learn about winscp.com, the console interface tool.

Verifying the Host Key or Certificate in Script

The first connection to an SSH server requires verification of the host key. To automate the verification in script, use -hostkey switch of open command to accept the expected host key automatically.

You can find the key fingerprint on Server and Protocol Information Dialog. You can also copy the key fingerprint to clipboard from the confirmation prompt on the first (interactive) connection using Copy Key button. Learn more about obtaining host key fingerprint.

FTPS/WebDAVS TLS/SSL certificate signed by untrusted authority may also need to be verified. To automate the verification in script, use -certificate switch of open command to accept the expected certificate automatically.

Running a Script under a Different Account (e.g., Using a Scheduler)

If you are going to run the script under a different account (for example using the Windows scheduler), don’t forget that WinSCP still needs to access its configuration. Note that when using registry as configuration storage, the settings are accessible only for your Windows account, so in such a case you may need to either transfer the configuration from your account registry to the other account’s registry or use the INI file instead.

Note that the configuration also includes verified SSH host keys and FTPS/WebDAVS TLS/SSL certificates.

Sharing Configuration with Graphical Mode

WinSCP in scripting/console mode shares configuration with graphical mode. This can be both advantageous and disadvantageous.

The advantage is that you can use graphical interface to configure options for which there are no script commands.

The disadvantage is that change to configuration in graphical mode may break your script (common example is enabling Existing files only// option for synchronization).

If you want to protect your script from such inadvertent change, you should isolate its configuration from graphical mode explicitly. To do that export your configuration to a separate INI file and reference it using /ini= command-line parameter.

Also consider setting the INI file read-only, to prevent WinSCP writing to it, when exiting. Particularly, if you are running multiple scripts in parallel, to prevent different instances of WinSCP trying to write it at the same time.

An ideal situation is when you are able to configure all the options you need using script commands only (option command, switches of other commands, session URL and raw site settings). Then you can force scripting mode to start with the default configuration using /ini=nul, avoiding need for the INI file.

Example

In the example below, WinSCP connects to example.com server with account user, downloads file and closes the session. Then it connects to the same server with the account user2 and uploads the file back.

# Automatically abort script on errors
option batch abort
# Disable overwrite confirmations that conflict with the previous
option confirm off
# Connect
open sftp://user:password@example.com/ -hostkey="ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
# Change remote directory
cd /home/user
# Force binary mode transfer
option transfer binary
# Download file to the local directory d:\
get examplefile.txt d:\
# Disconnect
close
# Connect as a different user
open sftp://user2:password@example.com/
# Change the remote directory
cd /home/user2
# Upload the file to current working directory
put d:\examplefile.txt 
# Disconnect
close
# Exit WinSCP
exit

Save the script to the file example.txt. To execute the script file use the following command.

winscp.com /script=example.txt

For simple scripts you can specify all the commands on command-line using /command switch:

winscp.com /command "option batch abort" "open sftp://user:password@example.com/" "get examplefile.txt d:\" "exit"

In Windows batch file, you can use ^ to split too long command-line to separate lines by escaping following new-line character:

winscp.com /command ^
    "option batch abort" ^
    "open sftp://user:password@example.com/" ^
    "get examplefile.txt d:\" ^
    "exit"

Converting Script to Code Based on .NET Assembly

When you find yourself limited by scripting capabilities, you may consider converting your script to code that uses WinSCP .NET assembly.

Scripting and Task Automation

Using Scripting

Checking Results

Environment Variables

Timestamp

Script Arguments

Case Sensitivity of File Names

Comments

Commands

The Console Interface Tool

Verifying the Host Key or Certificate in Script

Running a Script under a Different Account (e.g., Using a Scheduler)

Sharing Configuration with Graphical Mode

Example

Converting Script to Code Based on .NET Assembly

Further Reading

Documentation

Support

Associations

Follow Us