This is an old revision of the document!

Scripting and Task Automation

Advertisement

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

See command-line parameters to learn how to enter the console/scripting mode.

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

By default an interactive mode is used (the user is prompted in the same way as in GUI mode). To switch to a batch mode (all prompts are automatically answered negatively) use the command option batch abort. For the 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 host with certificate signed by untrusted authority requires verification of the certificate.

Advertisement

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.

When checking WinSCP exit code from a batch file, make sure you are using winscp.com.

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

Commands Syntax

All WinSCP commands have syntax:

command -switch -switch2 parameter1 parameter2 ... parametern

Command parameters that include space(s) have to be enclosed in double-quotes. To use double-quote literally, double it:

put "file with spaces and ""quotes"".html"

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

put "%FILE_TO_UPLOAD%"

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

put "%1%"

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

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

Advertisement

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 hostkey 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 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 certificates.

Sharing Configuration with Graphical Mode

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

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

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.

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 session settings). Then you can force scripting mode to start with the default configuration using /ini=nul, avoiding need for the INI file.

Example

The example below 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 using a password
# open sftp://user:password@example.com -hostkey="ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
# Connect
open sftp://user@example.com -hostkey="ssh-rsa 1024 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 user2@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

Advertisement

Save the script to the file example.txt. To execute the script file use the following command. As the script connects the session itself, using the command open, omit the session command-line parameter.

winscp.exe /console /script=example.txt

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

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

Instead of using open command you can also open a session using a command-line parameter. Note that in that case session is opened yet before script starts. Particularly option commands do not apply yet. Generally you should avoid using this method.

winscp.exe /console /script=example.txt user@example.com

Further Reading

  1. Generally do enclose reference to double-quotes to cope properly with spaces in its value.Back
  2. This is important particularly for FTP sessions.Back

Last modified: by martin