This is an old revision of the document!

Command-line Options

Advertisement

Parameters

Parameters for winscp.exe executable:

winscp.exe stored_session
winscp.exe <session_url>[/path/[file]]
winscp.exe [mysession] /synchronize [local_directory] [remote_directory] [/defaults]
winscp.exe [mysession] /keepuptodate [local_directory] [remote_directory] [/defaults]
winscp.exe [mysession] /upload file1 file2 file3 ... [/defaults]
winscp.exe [mysession] [/privatekey=<key_file>] [/hostkey=<fingerprint>]
winscp.exe [mysession] [/passive[=on|off]] [/implicit|explicitssl|explicittls]
winscp.exe [mysession] [/timeout=<sec>]
winscp.exe [mysession] [/rawsettings setting1=value1 setting2=value2 ...]
winscp.exe [/console] [/script=script_file] [/command command1 command2 ...] [/parameter param1 ...]
winscp.exe /ini=<inifile> /log=<logfile> /xmllog=<logfile>
winscp.exe /update
winscp.exe /help

Parameters for winscp.com executable:

winscp.com [/script=script_file] [/command command1 command2 ...] [/parameter param1 ...]
winscp.com /ini=<inifile> /log=<logfile>
winscp.com /help

Session

The first syntax opens the stored session (to open session, stored in folder, use path syntax “folder/session”).

Advertisement

The second creates the session specified by session URL and optionally by initial remote path. If the remote path is not ended by slash (/), it is treated as path to file (or even directory) that should be downloaded.

For security reasons, when protocol (such as sftp://) is provided as part of session URL (possible execution from web browser/Windows Explorer), all command-like parameters that cause any automatic action are ignored, including /defaults, /log, /script and /command.

Parameter /privatekey specifies local path to private key file.

Parameter /timeout specifies server response timeout.

Parameter /hostkey specifies fingerprint of expected host key (or several alternative fingerprints separated by semicolon). It makes WinSCP automatically accept hostkey with the fingerprint.

Parameter /passive enables passive (=on) or active (=off) transfer mode (FTP protocol only). This feature is available only in the latest beta release.

Parameters /implicit, /explicitssl and /explicittls enable respective methods of invoking FTPS.

Parameter /rawsettings allows configuring any session settings using raw format as in an INI file. E.g. to enable SSH compression and agent forwarding use /rawsettings Compression=1 AgentFwd=1. This feature is available only in the latest beta release.

When using scripting, use open command (and its switches) instead. This allows you settings script options before starting session.

With /log parameter you may turn on session logging to file specified by local path. With /xmllog parameter you may turn on XML logging to file specified by local path (This feature is available only in the latest beta release.).1 It either path can use the same patterns as in the logging preferences.

winscp.exe "My session"
winscp.exe sftp://martin@example.com /hostkey="ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
winscp.exe scp://test@example.com:2222 /privatekey=mykey.ppk
winscp.exe ftps://martin@example.com /implicit /certificate="xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
winscp.exe martin@example.com /log="C:\winscp.log"

Console/scripting mode

Parameter /console executes WinSCP in console (scripting) mode. Note that when using winscp.com, the console mode is implicit, so using /console parameter is redundant.

To run batch script either pass script file using /script parameter or specify the commands directly on command line using /command. In the latter case each following parameter is treated as single command. See syntax section and examples below for details how to deal with spaces and double-quotes.

If both /script and /command parameters are used, commands from script file are executed first. When the last command is not exit, regular non-batch mode follows.

Use parameter /parameter to specify list of arguments to be passed to script. It is recommended to escape the arguments with // switch.

With winscp.exe, if /console parameter is not used along with /script or /command, the script/command is executed without visual feedback (window).

Advertisement

winscp.com /script="C:\Documents and Settings\martin\Documents\myscript.txt"
winscp.com /command "open ""My session"" -hostkey=""ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"""
winscp.com /command "open ""My session""" "put ""C:\Documents and Settings\martin\Documents\myfile.dat"""
winscp.exe /console /script="myscript.txt"

Operations

The following parameters can be used to create a shortcut that initiates operation in GUI mode. They are not intended for automation, for that see scripting.

With /synchronize or /keepuptodate parameter WinSCP performs Synchronize or Keep remote directory up to date commands respectively on the specified session and directories. A dialog to set options is displayed first.

With /upload parameter WinSCP uploads specified files to initial remote directory of session2. A dialog to set options is displayed first.

Use /defaults parameter along with /upload, /synchronize or /keepuptodate to skip the settings dialog and start the operation straight away with default settings.

It is recommended to escape the arguments with // switch.

winscp.exe /defaults /synchronize // "C:\Documents and Settings\martin\Documents\MySite" /home/martin/public_html

Configuration

With /ini parameter you may specify local path to configuration INI file. It effectively disables using registry as configuration storage. If the file does not exist, default configuration will be used and the file will be created.

winscp.exe /ini="C:\Documents and Settings\martin\Documents\myconfig.ini"

Auxiliary

When run with /update parameter, WinSCP only checks for its updates.

Parameter /help shows usage (overview similar to this).

Syntax

Command-line parameters that include space(s) must be enclosed in double-quotes:

winscp.exe /ini="C:\Documents and Settings\martin\Documents\myconfig.ini"

Advertisement

To use the double-quote as a literal, use two double quotes sequentially. For example, the /command expects that the script will be structured as an in-line FTP script and that each line of the script is enclosed in double quotes. In addition, any part of a line within the script that includes spaces is expected to be enclosed with double quotes within the line so that the complete line is passed as a single string doubling double-quotes:

winscp.com /command "open ""My session""" "put ""C:\Documents and Settings\martin\Documents\myfile.dat"""
                    |<- Script line 1 ->| |<-                   Script line 2                         ->|

An Argument that begins with a slash is considered a switch. If you need to pass a parameter with such syntax (i.e. typically a remote path like /root), you need to use special switch // (two slashes) before the argument. The switch // signals that any arguments following the double slash are considered part of the parameter to be passed. Example:

winscp.exe /synchronize // "C:\Documents and Settings\martin\Documents\MySite" /root

Executables

Learn about two WinSCP executables, winscp.exe and winscp.com.

Hint

If you are going to run WinSCP from command-line often, you may wish to add WinSCP installation directory to search path.

  1. For backwards compatibility, XML logging can also be enabled using /log parameter with filename ending with .xml extension.Back
  2. Parameter is primarily intended to allow Windows Explorer’s ‘Send To’ menu integrationBack

Last modified: by 207.107.36.14