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 Syntax
- 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
- Generating Script
- Converting Script to Code Based on .NET Assembly
- Further Reading
Enter the console/scripting mode by using
/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
The script file must use UTF-8 or UTF-16 (with BOM) encoding.
When running commands specified using
/command, batch mode is used implicitly and overwrite confirmations are turned off. 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.
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.
For more details, refer to How do I know that script completed successfully?
All WinSCP commands have syntax:
command -switch -switch2 parameter1 parameter2 ... parametern
Command Parameters with Spaces
Command parameters that include space(s) have to be surrounded by double-quotes. To use double-quote literally, double it:
put "file with spaces and ""quotes"".html"
Note that when you are specifying commands on command-line using
/command, you need to surround each command by double-quote and escape the in-command double-quotes by doubling them.
To debug the quoting, enable session logging on level Debug 1 (
/loglevel=1). The log will show how WinSCP understands both your command-line and individual scripting commands.
You can use environment variables in the commands, with syntax
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
- References to undefined variables are kept intact (not removed).
- You can use
%WINSCP_PATH%to refer to WinSCP executable path.
WinSCP automatically resolves
%TIMESTAMP[rel]#format% to a real time (optionally to a past or future time) with the given format. The
format may include
yyyy for year,
mm for month,
dd for day,
hh for hour,
nn for minute and
ss for second. For example, the
%TIMESTAMP#yyyy-mm-dd% resolves to
2016-06-22 on 22 June 2016. See other formats you can use.
rel part, with syntax
[-+]time[YDHNS], produces past (
-) or future (
+) timestamps. One of the following units must be used:
N (minutes) or
S (seconds). For example, the
-1D meaning one day in the past) resolves to
2016-06-21 on 22 June 2016.
%TIMESTAMP...% on a command-line in a batch file, you need to escape the
% by doubling it to
%%TIMESTAMP...%%, to avoid a batch file interpreter trying to resolve the variable.
You can reference script arguments (passed on command-line using parameter
/parameter) using syntax
N is ordinal number of argument: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 properly.2
To insert comments into the script file, start the line with
# 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.
|call||Executes arbitrary remote shell command|
|cd||Changes remote working directory|
|checksum||Calculates checksum of remote file|
|chmod||Changes permissions of remote file|
|cp||Duplicates remote file|
|echo||Prints message onto script output|
|exit||Closes all sessions and terminates the program|
|get||Downloads file from remote directory to local directory|
|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
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 fingerprints to clipboard command (in the script, use SHA-256 fingerprint of the host key only). 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 Task Scheduler), make sure the script does not rely on a configuration settings that might differ on the other account. When using registry as configuration storage, the settings are accessible only for your Windows account. Ideally, make sure the script does not rely on any external configuration, to make it completely portable. Note that the configuration also includes verified SSH host keys and FTPS/WebDAVS TLS/SSL certificates.
For details, see the next section and Why does WinSCP not work in a new environment (operating system, machine, user account, network), when it works for me in a different environment already?
You can have WinSCP generate a script template for you.
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.
# Connect open sftp://user:firstname.lastname@example.org/ -hostkey="ssh-rsa 2048 xxxxxxxxxxx..." # Change remote directory cd /home/user # Download file to the local directory d:\ get examplefile.txt d:\ # Disconnect close # Connect as a different user open sftp://user2:email@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 /ini=nul /script=example.txt
For simple scripts you can specify all the commands on command-line using
winscp.com /ini=nul /command "open sftp://user:firstname.lastname@example.org/ -hostkey=""ssh-rsa 2048 xxxxxxxxxxx...""" "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 /ini=nul /command ^ "open sftp://user:email@example.com/ -hostkey=""ssh-rsa 2048 xxxxxxxxxxx...""" ^ "get examplefile.txt d:\" ^ "exit"
See other useful example scripts.
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.