This is an old revision of the document!

Scripting/Automation

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.

Advertisement

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

WinSCP returns 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.

Commands

The following commands are implemented:

Command Description
call Executes arbitrary remote shell command
cd Changes remote working directory
chmod Changes permissions of remote file
close Closes session
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
synchronize Synchronizes remote directory with local one

Advertisement

The Console Interface Tool

As WinSCP.exe is a GUI application, it cannot inherit the console window when run from another console application (such as the Windows command-prompt). To allow this, run WinSCP using the console interface tool WinSCP.com (you can find WinSCP.com in the main installation package).

With console interface tool you can also use input/output redirection and pipes.

Verifying the Host Key in Script

The first connection to an SSH server requires verification of the host key. To automate the verification in script, you can use command-line parameter hostkey (or switch of open command with the same name) to accept the expected hostkey automatically.

You can find the fingerprint on Server and Protocol Information Dialog.

Running a Script under a Different Account

If you are going to run the script under a different account (for example using the Windows scheduler), note that WinSCP may store its configuration to the user part of Windows Registry by default. So you may need to either transfer the configuration from your account registry to the other account registry or use the INI file instead.

Note that the configuration also includes verified SSH host keys. See respective note above.

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 answer all prompts negatively not to stall
# the script on errors
option batch on
# Disable overwrite confirmations that conflict with the previous
option confirm off
# Connect using a password
# open user:password@example.com
# Connect
open user@example.com
# 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

Instead of using open command you can also open a session using a command-line parameter.

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

Useful Scripts

You can see list of scripts other users found useful.

For more tips, see also FAQs on scripting.

Last modified: by martin