Command-line Options
Advertisement
Parameters
Parameters for winscp.exe
executable:
winscp.exe site|workspace|folder winscp.exe <session_url>[/path/[file]] winscp.exe [mysession] [/sessionname=<name>] winscp.exe [mysession] [/newinstance] winscp.exe [mysession] /edit <path> winscp.exe [mysession] /browse[=<file>] winscp.exe [mysession] /synchronize [local_directory] [remote_directory] [/defaults[=secs]] winscp.exe [mysession] /keepuptodate [local_directory] [remote_directory] [/defaults[=secs]] winscp.exe [mysession] /refresh [path] winscp.exe [mysession] /upload file1 file2 file3 ... [/defaults[=secs]] winscp.exe [mysession] [/privatekey=<file> [/passphrase=<passphrase>]] winscp.exe [mysession] [/hostkey=<fingerprint>] winscp.exe [mysession] [/username=<user>] [/password=<pass>] winscp.exe [mysession] [/passwordsfromfiles] winscp.exe [mysession] [/clientcert=<file> [/passphrase=<passphrase>]] winscp.exe [mysession] [/certificate=<fingerprint>] winscp.exe [mysession] [/passive[=on|off]] [/implicit|explicit] 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 [/log=<logfile> [/loglevel=<level>] [/logsize=[<count>*]<size>]] [/xmllog=<logfile> [/xmlgroups]] winscp.exe [/ini=<inifile>] winscp.exe [/rawconfig config1=value1 config2=value2 ...] winscp.exe [/rawtransfersettings setting1=value1 setting2=value2 ...] winscp.exe /batchsettings <site_mask> setting1=value1 setting2=value2 ... winscp.exe /keygen keyfile [/output=<file>] [/changepassphrase] winscp.exe /keygen keyfile [/comment=<text>] [/certificate=<file>] winscp.exe /update winscp.exe /info winscp.exe /help
Advertisement
Parameters for winscp.com
executable:
winscp.com [/script=script_file] [/command command1 command2 ...] [/parameter // param1 ...] winscp.com [/stdout[=binary|chunked]] [/stdin] winscp.com [/log=<logfile> [/loglevel=<level>] [/logsize=[<count>*]<size>]] [/xmllog=<logfile> [/xmlgroups]] [/nointeractiveinput] winscp.com [/ini=<inifile>] winscp.com [/rawconfig config1=value1 config2=value2 ...] winscp.com /batchsettings <site_mask> setting1=value1 setting2=value2 ... winscp.com /keygen keyfile [/output=<file>] [/changepassphrase] winscp.com /keygen keyfile [/comment=<text>] [/certificate=<file>] winscp.com /info winscp.com /help
Session
The first syntax opens the site. To open site, stored in folder, use path syntax “folder/site”. You can also open workspace or all sites in site folder.
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.
The parameter /sessionname
specifies a custom name of the session to be used instead of the automatically generated name in a format username@hostname
or to override the name of the saved site.
If there’s already an idle WinSCP instance running, the session(s) opens in the existing instance. To force the session to open in a new instance of WinSCP, use /newinstance
parameter.
The parameter /privatekey
specifies a local path to an SSH private key file. If the key file is encrypted, use the /passphrase
to specify its passphrase. The passphrase can be read from a file.
The parameter /hostkey
specifies the fingerprint of the expected SSH host key (or several alternative fingerprints separated by a semicolon). It makes WinSCP automatically accept the host key with the fingerprint.
You can use the parameters /username
and /password
as an alternative way to specify the credentials. The credentials are normally part of the session URL. Using these switches has the advantage of not needing to URL-encode special characters. The password can be read from a file.
With parameter /passwordsfromfiles
, the values of /password
, /passphrase
and in general all passwords from all sources are interpreted as paths to files, where the actual passwords are read from. The files must use UTF-8 or UTF-16 encoding.1
The parameter /clientcert
specifies a local path to FTPS or WebDAVS TLS/SSL client certificate. If the certificate is encrypted, use the /passphrase
to specify its passphrase.
When a FTPS or WebDAVS server TLS/SSL certificate is not trusted (typically a self-signed certificate), use the parameter /certificate
to specify the fingerprint of the untrusted certificate. It makes WinSCP trust the certificate. Several alternative fingerprints can be separated by a semicolon.
The parameter /passive
enables a passive (=on
) or an active (=off
) transfer mode (FTP protocol only).
Advertisement
The parameters /implicit
, and /explicit
enable respective method of invoking FTPS.
The parameter /timeout
specifies server response timeout.
The parameter /rawsettings
allows configuring any site settings using raw format as in an INI file. E.g. to enable an SSH compression and an agent forwarding, use /rawsettings Compression=1 AgentFwd=1
. The parameter must come after the session URL (if any).
When using scripting, use the open
command (and its switches) instead.
Examples:
winscp.exe "My site" winscp.exe sftp://martin:password@example.com/ /hostkey="ssh-rsa 2048 xxxxxxxxxxx..." winscp.exe scp://test@example.com:2222/ /privatekey=mykey.ppk winscp.exe ftps://martin:password@example.com/
Logging
With /log
parameter you may turn on session logging to file specified by local path. In the path you can use the same patterns as in the logging preferences.
Use parameter /loglevel
to change logging level. The value can be in range -1
…2
(for Reduced, Normal, Debug 1 and Debug 2 logging levels respectively). Append additional *
to enable password logging (e.g. /loglevel=2*
).2
Use parameter /logsize
to configure log file size limit and log file rotation. Specify maximum size in bytes, optionally with K
, M
or G
units. Optionally you can limit number of archived log files using count*
prefix. For example /logsize=5*10M
will limit log file size to 10 MB and will allow up to 5 archived logs.
winscp.exe sftp://martin@example.com/ /log="C:\winscp.log" /loglevel=0
With /xmllog
parameter you may turn on XML logging to file specified by local path.3 In the path you can use the same patterns as in the logging preferences.
Use parameter /xmlgroups
along with /xmllog
, to group all XML log elements belonging to the same command under parent group
element.
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
Use the parameter /stdout
to enable streaming files to the standard output of winscp.com
. When the parameter is used, the get
command will stream the downloaded file(s) to the standard output, when -
is used as a download target. By default (or with the binary
flag), the files are streamed unmodified. With the chunked
flag, the files are individually encoded using Chunked transfer encoding, what allows separating contents of multiple streamed files. When the parameter is used, all console output that would normally be printed to the standard output is redirected to the error output. Streaming is supported with the SFTP and FTP protocols only.
Use the parameter /stdin
to enable streaming files from the standard input of winscp.com
. When the parameter is used, the put
command will stream the standard input to the remote server, when -
is used as an upload source. Implies /nointeractiveinput
. Streaming is supported with the SFTP and FTP protocols only.
Use parameter /nointeractiveinput
, when feeding commands to winscp.com
using standard input, to make sure prompts for anything other than commands (such as password prompts) are cancelled. Also prevents error message popping up when fatal error occurs while starting WinSCP. When combined with /xmllog
the fatal error is recorded in the XML log.
Examples:
winscp.com /script="C:\Users\martin\Documents\myscript.txt" winscp.com /command "open sftp://martin@example.com/ -hostkey=""ssh-rsa 2048 xxxx...""" "exit" winscp.exe /console /script="myscript.txt" /log="myscript.log"
You can have WinSCP generate a scripting command-line for you.
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.
Use /edit
to open a remote file in WinSCP internal editor.
Use /browse
to select the specified file in (both) file panel(s). The switch can also be used together with a file URL for the same effect, overriding the default download action.
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 session.4 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. Alternatively you can specify a number of seconds, to actually show the settings dialogs, but have them automatically submit after the specified time elapses.
Use the /refresh
parameter to reload remote panel of all running instances of WinSCP. If a session is specified on command-line, only instances that have that session as active are refreshed. If a path is specified after the /refresh
, only that directory is refreshed.
It is recommended to escape the arguments with // switch.
Example:
winscp.exe /defaults /synchronize // "C:\Users\martin\Documents\MySite" /home/martin/public_html
Advertisement
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:\Users\martin\Documents\myconfig.ini"
Use nul
instead of path to force WinSCP start with its default configuration and not save the configuration on exit.
With /rawconfig
parameter you can set any configuration settings using raw format as in an INI file. E.g. to configure an external IP address use /rawconfig Interface\ExternalIpAddress=198.51.100.10
. The parameter must come after a session URL (if any). The configuration set this way is preserved.
With /rawtransfersettings
you can set any transfer settings using raw format as in an INI file. E.g. to enable preserving of directory timestamps, use /rawtransfersettings PreserveTimeDirs=1
. The configuration set this way is preserved. In scripting, it is better to use -rawtransfersettings
switch of individual scripting commands, like get
, put
, etc.
Mass-modification of sites
Use /batchsettings
to mass-modify stored sites. The first argument is a mask to select sites to modify. Use a syntax of basic file masks. You can also use path mask to select sites based on their folders. The other arguments define new values for site settings. Use the same syntax as for /rawsettings
.
For example to configure a proxy for all sites in a “clients” folder, use:
winscp.exe /batchsettings clients/* ProxyMethod=3 ProxyHost=proxy
Private key conversion and modification
Use the /keygen
switch to convert private keys from other formats to a PuTTY .ppk
format or to change their passphrase or comment or to add a certificate. You can combine a conversion and key changes into one command.
A parameter after the /keygen
switch specifies a path to an input private key file. The input key can be in OpenSSH or ssh.com format (when converting the key to the PuTTY format) or in the PuTTY format (when modifying the key).
When converting the key from other format, you need to specify an output key path using the /output
switch. When modifying a PuTTY key, the existing file is overwritten, if /output
is not specified.
Use /changepassphrase
switch to change the key passphrase.
Use /comment
switch to change the key comment.
Use /certificate
switch to add an certificate to the key.
For example, to convert key mykey.pem
from OpenSSH format to mykey.ppk
in PuTTY format and set its comment:
winscp.com /keygen mykey.pem /output=mykey.ppk /comment="Converted from OpenSSH format"
Advertisement
To change the passphrase of existing mykey.ppk
:
winscp.com /keygen mykey.ppk /changepassphrase
For a compatibility with *nix puttygen
, the -o
, -P
, -C
, --old-passphrase
and --certificate
switches are understood as aliases to /output
, /changepassphrase
, /comment
, /passphrase
and /certificate
respectively. The --new-passphrase
is recognized too. So, for features supported by WinSCP, you can use the same arguments as for puttygen
, just prefixed with /keygen
:
winscp.com /keygen mykey.pem -o mykey.ppk -C "Converted from OpenSSH format"
Auxiliary
When run with /update
parameter, WinSCP only checks for its updates.
The parameter /info
lists the supported SSH and TLS/SSL algorithms.
Parameter /help
shows usage (overview similar to this).
Syntax
Command-line parameters that include space(s) must be surrounded by double-quotes:
winscp.exe /ini="C:\Users\martin\Documents\myconfig.ini"
To use the double-quote as a literal, use two double-quotes sequentially. For example, the /command
expects that each script command is surrounded by double quotes, so that it is passed as a single command-line argument. In addition, any script command argument that includes spaces is expected to be surrounded by double-quotes within the command (see doubling double-quotes):
winscp.com /command "open sftp://... -hostkey=""ssh-rsa ...""" "put ""C:\my file.dat""" <- Script command 1 -> <- Script command 2 ->
When executing such command from PowerShell, you additionally have to escape the doubled inner double-quotes with `
(backtick) to prevent PowerShell from interpreting them on its own:5
winscp.com /command "open sftp://... -hostkey=`"`"ssh-rsa ...`"`"" "put `"`"C:\my file.dat`"`"" <- Script command 1 -> <- Script command 2 ->
To debug the quoting, enable session logging on level Debug 1 (/loglevel=1
). The log will show how WinSCP understands your command-line.
An argument that begins with a slash is considered a switch. To pass a parameter that itself starts with the slash in its syntax (i.e. a remote path like /root
), use the special switch //
(two slashes) before the argument. The switch //
denotes that all following arguments are not switches. Example:
winscp.exe /synchronize // "C:\Users\martin\Documents\MySite" /root
Advertisement
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.
Running from Bash
When running WinSCP from a shell, where /switch
is interpreted as a path, such as Git Bash, use a dash (-
) instead of the slash (/
) for switches. For example:
./WinSCP.com -script="myscript.txt" -log="myscript.log"
- With UTF-8 encoding use of BOM is optional. With UTF-16 the BOM is mandatory. Only the first line of the file is considered. Use of more lines is reserved for the future.Back
- Append
*-
to disable password logging.Back - For backward compatibility, XML logging can also be enabled using
/log
parameter with filename ending with.xml
extension.Back - Parameter is primarily intended to allow Windows File Explorer’s ‘Send To’ menu integration.Back
- Alternative way is using single quotes instead of outer double quotes.Back