Scripting and Task Automation

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>

This feature is available only in the latest release.

put "%1%"

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

key>ActivationRandomness</key>\r
string>84AE7F6C-6183-47AE-9E81-AB177E6D1BB2</string>\r
key>ActivationState</key>\r
string>Activated</string>\r
key>BuildVersion</key>\r
string>12D508</string>\r
key>DeviceCertRequest</key>\r
data>\r
S0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQnhEQ0NBUzBDQVFB\r
2dZTXhMVEFyQmdOVkJBTVRKRUpETlRoRE0wRTFMVEUzUlRBdE5EWkVNeTA0TTBZMwpM\r
E00TVRoRk5VUXlOMEkwTkRFTE1Ba0dBMVVFQmhNQ1ZWTXhDekFKQmdOVkJBZ1RBa05C\r
VJJd0VBWURWUVFICkV3bERkWEJsY25ScGJtOHhFekFSQmdOVkJBb1RDa0Z3Y0d4bElF\r
HVZeTR4RHpBTkJnTlZCQXNUQm1sUWFHOXUKWlRDQm56QU5CZ2txaGtpRzl3MEJBUUVG\r
UFPQmpRQXdnWWtDZ1lFQTJUWHRibUw0NXVJWWJiU1ZPV1kxT2VaKwpZU1BhQ2NjRzM1\r
TBMNVpNb29LVnhOakxIREpxMnAzbERiTnN5YzZkT0pqZGtZZnNTYTVVYWF6TVQzQXB1\r
FpOCjdaOERXM0F1QXE5b3h3bi9FOUlNOTdKcmVtekJiYng5cVU3aUpjOURlZXdyblN4\r
0QyVFhZMnp6TjZwT0poVXAKSWM5MDNuQUwzTVM1MjFXVml0MENBd0VBQWFBQU1BMEdD\r
3FHU0liM0RRRUJCUVVBQTRHQkFLdDJQZnBEekFsTwphQVFFWWtFU3FlTDRrNDBiVUla\r
WRxK1pGbnk4RitHRC9ZR3FtUFg0K1lySWErVkExdlFBWk9XSFd5RkdPekZLCnM5MXJM\r
UNWVkEvK3NxVGZMdlY4VGNoaE1yUGhBSFlHL1pmUGdYQXduY2gvUG5XTnNYWmZsOEpU\r
GhWdkFQKzMKbnRYN3dvSXZvN1FHUklSdVRYOENhVzdza2dCeXorU0sKLS0tLS1FTkQg\r
0VSVElGSUNBVEUgUkVRVUVTVC0tLS0tCg==\r
/data>\r
key>DeviceClass</key>\r
string>iPad</string>\r
key>DeviceVariant</key>\r
string>A</string>\r
key>FMiPAccountExists</key>\r
false/>\r
key>ModelNumber</key>\r
string>MC769</string>\r
key>ProductType</key>\r
string>iPad2,1</string>\r
key>ProductVersion</key>\r
string>8.2</string>\r
key>RegionCode</key>\r
string>ZP</string>\r
key>RegionInfo</key>\r
string>ZP/A</string>\r
key>SerialNumber</key>\r
string>DLXGQS0QDFHW</string>\r
key>UniqueChipID</key>\r
integer>2688114539789</integer>\r
key>UniqueDeviceID</key>\r
string>5aab68580e5535640935f7f7800fc7134ef49b8d</string>\r

</dict>\r </plist>\r

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

# Connect to the server
open mysession

The following commands are implemented.

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

Learn about winscp.com, the console interface tool.

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

��0U

�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

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.

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.

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"

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

• Guide to scripting;
• FAQs about scripting;
• Useful example scripts;
• WinSCP .NET assembly.