commandline » Revisions »
Differences
This shows you the differences between the selected revisions of the page.
| commandline 2021-07-10 | commandline 2024-12-16 (current) | ||
| Line 1: | Line 1: | ||
| ====== Command-line Options ====== | ====== Command-line Options ====== | ||
| + | |||
| + | |||
| ===== [[parameters]] Parameters ===== | ===== [[parameters]] Parameters ===== | ||
| Parameters for ''[[executables|winscp.exe]]'' executable: | Parameters for ''[[executables|winscp.exe]]'' executable: | ||
| - | <code batch> | + | &amp;lt;code batch&amp;gt; |
| winscp.exe site|workspace|folder | winscp.exe site|workspace|folder | ||
| - | winscp.exe <session_url>[/path/[file]] | + | winscp.exe &amp;lt;session_url&amp;gt;[/path/[file]] |
| - | winscp.exe [mysession] [/sessionname=<name>] | + | winscp.exe [mysession] [/sessionname=&amp;lt;name&amp;gt;] |
| winscp.exe [mysession] [/newinstance] | winscp.exe [mysession] [/newinstance] | ||
| - | winscp.exe [mysession] /edit <path> | + | winscp.exe [mysession] /edit &amp;lt;path&amp;gt; |
| - | winscp.exe [mysession] /browse[=<file>] | + | winscp.exe [mysession] /browse[=&amp;lt;file&amp;gt;] |
| winscp.exe [mysession] /synchronize [local_directory] [remote_directory] [/defaults[=secs]] | winscp.exe [mysession] /synchronize [local_directory] [remote_directory] [/defaults[=secs]] | ||
| winscp.exe [mysession] /keepuptodate [local_directory] [remote_directory] [/defaults[=secs]] | winscp.exe [mysession] /keepuptodate [local_directory] [remote_directory] [/defaults[=secs]] | ||
| winscp.exe [mysession] /refresh [path] | winscp.exe [mysession] /refresh [path] | ||
| winscp.exe [mysession] /upload file1 file2 file3 ... [/defaults[=secs]] | winscp.exe [mysession] /upload file1 file2 file3 ... [/defaults[=secs]] | ||
| - | winscp.exe [mysession] [/privatekey=<file> [/passphrase=<passphrase>]] | + | winscp.exe [mysession] [/privatekey=&amp;lt;file&amp;gt; [/passphrase=&amp;lt;passphrase&amp;gt;]] |
| - | winscp.exe [mysession] [/hostkey=<fingerprint>] | + | winscp.exe [mysession] [/hostkey=&amp;lt;fingerprint&amp;gt;] |
| - | winscp.exe [mysession] [/username=<user>] [/password=<pass>] | + | winscp.exe [mysession] [/username=&amp;lt;user&amp;gt;] [/password=&amp;lt;pass&amp;gt;] |
| - | winscp.exe [mysession] [/clientcert=<file> [/passphrase=<passphrase>]] | + | winscp.exe [mysession] [/passwordsfromfiles] |
| - | winscp.exe [mysession] [/certificate=<fingerprint>] | + | winscp.exe [mysession] [/clientcert=&amp;lt;file&amp;gt; [/passphrase=&amp;lt;passphrase&amp;gt;]] |
| + | winscp.exe [mysession] [/certificate=&amp;lt;fingerprint&amp;gt;] | ||
| winscp.exe [mysession] [/passive[=on|off]] [/implicit|explicit] | winscp.exe [mysession] [/passive[=on|off]] [/implicit|explicit] | ||
| - | winscp.exe [mysession] [/timeout=<sec>] | + | winscp.exe [mysession] [/timeout=&amp;lt;sec&amp;gt;] |
| winscp.exe [mysession] [/rawsettings setting1=value1 setting2=value2 ...] | winscp.exe [mysession] [/rawsettings setting1=value1 setting2=value2 ...] | ||
| - | winscp.exe [/console] [/script=<script_file>] [/command command1 command2 ...] | + | winscp.exe [/console] [/script=&amp;lt;script_file&amp;gt;] [/command command1 command2 ...] |
| [/parameter // param1 ...] | [/parameter // param1 ...] | ||
| - | winscp.exe [/log=<logfile> [/loglevel=<level>] [/logsize=[<count>*]<size>]] | + | winscp.exe [/log=&amp;lt;logfile&amp;gt; [/loglevel=&amp;lt;level&amp;gt;] [/logsize=[&amp;lt;count&amp;gt;*]&amp;lt;size&amp;gt;]] |
| - | [/xmllog=<logfile> [/xmlgroups]] | + | [/xmllog=&amp;lt;logfile&amp;gt; [/xmlgroups]] |
| - | winscp.exe [/ini=<inifile>] | + | winscp.exe [/ini=&amp;lt;inifile&amp;gt;] |
| winscp.exe [/rawconfig config1=value1 config2=value2 ...] | winscp.exe [/rawconfig config1=value1 config2=value2 ...] | ||
| winscp.exe [/rawtransfersettings setting1=value1 setting2=value2 ...] | winscp.exe [/rawtransfersettings setting1=value1 setting2=value2 ...] | ||
| - | winscp.exe /batchsettings <site_mask> setting1=value1 setting2=value2 ... | + | winscp.exe /batchsettings &amp;lt;site_mask&amp;gt; setting1=value1 setting2=value2 ... |
| - | winscp.exe /keygen keyfile [/output=<file>] [/changepassphrase] [/comment=<text>] | + | winscp.exe /keygen keyfile [/output=&amp;lt;file&amp;gt;] [/changepassphrase] |
| + | winscp.exe /keygen keyfile [/comment=&amp;lt;text&amp;gt;] [/certificate=&lt;file&gt;] | ||
| winscp.exe /update | winscp.exe /update | ||
| winscp.exe /info | winscp.exe /info | ||
| winscp.exe /help | winscp.exe /help | ||
| - | </code> | + | &amp;lt;/code&amp;gt; |
| Parameters for ''[[executables|winscp.com]]'' executable: | Parameters for ''[[executables|winscp.com]]'' executable: | ||
| - | <code batch> | + | &amp;lt;code batch&amp;gt; |
| winscp.com [/script=script_file] [/command command1 command2 ...] | winscp.com [/script=script_file] [/command command1 command2 ...] | ||
| [/parameter // param1 ...] | [/parameter // param1 ...] | ||
| winscp.com [/stdout[=binary|chunked]] [/stdin] | winscp.com [/stdout[=binary|chunked]] [/stdin] | ||
| - | winscp.com [/log=<logfile> [/loglevel=<level>] [/logsize=[<count>*]<size>]] | + | winscp.com [/log=&amp;lt;logfile&amp;gt; [/loglevel=&amp;lt;level&amp;gt;] [/logsize=[&amp;lt;count&amp;gt;*]&amp;lt;size&amp;gt;]] |
| - | [/xmllog=<logfile> [/xmlgroups]] [/nointeractiveinput] | + | [/xmllog=&amp;lt;logfile&amp;gt; [/xmlgroups]] [/nointeractiveinput] |
| - | winscp.com [/ini=<inifile>] | + | winscp.com [/ini=&amp;lt;inifile&amp;gt;] |
| winscp.com [/rawconfig config1=value1 config2=value2 ...] | winscp.com [/rawconfig config1=value1 config2=value2 ...] | ||
| - | winscp.com /batchsettings <site_mask> setting1=value1 setting2=value2 ... | + | winscp.com /batchsettings &amp;lt;site_mask&amp;gt; setting1=value1 setting2=value2 ... |
| - | winscp.com /keygen keyfile [/output=<file>] [/changepassphrase] [/comment=<text>] | + | winscp.com /keygen keyfile [/output=&amp;lt;file&amp;gt;] [/changepassphrase] |
| - | winscp.exe /info | + | winscp.com /keygen keyfile [/comment=&amp;lt;text&amp;gt;] [/certificate=&lt;file&gt;] |
| + | winscp.com /info | ||
| winscp.com /help | winscp.com /help | ||
| - | </code> | + | &amp;lt;/code&amp;gt; |
| ==== [[session]] Session ==== | ==== [[session]] Session ==== | ||
| Line 58: | Line 64: | ||
| 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. | 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 idle WinSCP instance running, the session(s) opens in the existing instance. To force session open in new instance of WinSCP, use ''/==newinstance=='' parameter. | + | 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. If no session is specified on command-line, [[ui_login|Login dialog]] opens to select one. |
| - | The parameter ''/privatekey'' specifies a [[local_path|local path]] to an [[public_key#private|SSH private key file]]. If the key file is encrypted, use the ''/passphrase'' to specify its passphrase. | + | The parameter ''/==privatekey=='' specifies a [[local_path|local path]] to an [[public_key#private|SSH private key file]]. If the key file is encrypted, use the ''/passphrase'' to specify its passphrase. The passphrase [[#passwordsfromfiles|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 [[ssh_verifying_the_host_key|accept the host key]] with the fingerprint. | The parameter ''/hostkey'' specifies the fingerprint of the expected SSH host key (or several alternative fingerprints separated by a semicolon). It makes WinSCP automatically [[ssh_verifying_the_host_key|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|session URL]]. Using these switches has the advantage of not needing to [[session_url#special|URL-encode special characters]]. | + | 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|session URL]]. Using these switches has the advantage of not needing to [[session_url#special|URL-encode special characters]]. The password [[#passwordsfromfiles|can be read from a file]]. |
| + | |||
| + | With parameter ''/==passwordsfromfiles=='', the values of [[#username|''/password'']], [[#privatekey|''/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.((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.)) | ||
| The parameter ''/clientcert'' specifies a [[local_path|local path]] to FTPS or WebDAVS [[tls#client_certificate|TLS/SSL client certificate]]. If the certificate is encrypted, use the ''/passphrase'' to specify its passphrase. | The parameter ''/clientcert'' specifies a [[local_path|local path]] to FTPS or WebDAVS [[tls#client_certificate|TLS/SSL client certificate]]. If the certificate is encrypted, use the ''/passphrase'' to specify its passphrase. | ||
| Line 84: | Line 92: | ||
| <code batch> | <code batch> | ||
| winscp.exe "My site" | winscp.exe "My site" | ||
| - | winscp.exe sftp://martin:password@example.com/ /hostkey="ssh-rsa 2048 xxxxxxxxxxx...=" | + | winscp.exe sftp://martin:password@example.com/ /hostkey="ssh-rsa 2048 xxxxxxxxxxx..." |
| winscp.exe scp://test@example.com:2222/ /privatekey=mykey.ppk | winscp.exe scp://test@example.com:2222/ /privatekey=mykey.ppk | ||
| winscp.exe ftps://martin:password@example.com/ | winscp.exe ftps://martin:password@example.com/ | ||
| Line 91: | Line 99: | ||
| ==== [[logging]] Logging ==== | ==== [[logging]] Logging ==== | ||
| - | With ''/log'' parameter you may turn on [[logging|session logging]] to file specified by [[local_path|local path]]. | + | With ''/log'' parameter you may turn on [[logging|session logging]] to file specified by [[local_path|local path]]. In the path you can use the same patterns as in the [[ui_pref_logging#session_log|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*'').((Append ''*-'' to disable password logging.)) | 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*'').((Append ''*-'' to disable password logging.)) | ||
| - | 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. | + | 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. |
| <code batch> | <code batch> | ||
| Line 101: | Line 109: | ||
| </code> | </code> | ||
| - | With ''/xmllog'' parameter you may turn on [[logging_xml|XML logging]] to file specified by local path. ((For backward compatibility, XML logging can also be enabled using ''/log'' parameter with filename ending with ''.xml'' extension.)) In either path you can use the same patterns as in the [[ui_pref_logging|logging preferences]]. | + | With ''/xmllog'' parameter you may turn on [[logging_xml|XML logging]] to file specified by local path. ((For backward compatibility, XML logging can also be enabled using ''/log'' parameter with filename ending with ''.xml'' extension.)) In the path you can use the same patterns as in the [[ui_pref_logging#session_log|logging preferences]]. |
| Use parameter ''/xmlgroups'' along with ''/xmllog'', to [[logging_xml#group|group]] all XML log elements belonging to the same command under parent ''group'' element. | Use parameter ''/xmlgroups'' along with ''/xmllog'', to [[logging_xml#group|group]] all XML log elements belonging to the same command under parent ''group'' element. | ||
| Line 117: | Line 125: | ||
| With ''[[executables|winscp.exe]]'', if ''/console'' parameter is not used along with ''/script'' or ''/command'', the script/command is executed without visual feedback (window). | With ''[[executables|winscp.exe]]'', if ''/console'' parameter is not used along with ''/script'' or ''/command'', the script/command is executed without visual feedback (window). | ||
| - | Use the parameter ''/==stdout=='' to enable streaming files to the [[executables#redirection|standard output of ''winscp.com'']]. When the parameter is used, the [[scriptcommand_get|''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 [[https://en.wikipedia.org/wiki/Chunked_transfer_encoding|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|SFTP protocol]] only. | + | Use the parameter ''/==stdout=='' to enable ==stream==ing files to the [[executables#redirection|standard output of ''winscp.com'']]. When the parameter is used, the [[scriptcommand_get|''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 [[https://en.wikipedia.org/wiki/Chunked_transfer_encoding|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|SFTP]] and [[ftp|FTP]] protocols only. |
| - | Use the parameter ''/==stdin=='' to enable streaming files from the [[executables#redirection|standard input of ''winscp.com'']]. When the parameter is used, the [[scriptcommand_put|''put'' command]] will stream the standard input to the remote server, when ''-'' is used as an upload source. Implies [[#nointeractiveinput|''/nointeractiveinput'']]. Streaming is supported with the SFTP protocol only. | + | Use the parameter ''/==stdin=='' to enable streaming files from the [[executables#redirection|standard input of ''winscp.com'']]. When the parameter is used, the [[scriptcommand_put|''put'' command]] will stream the standard input to the remote server, when ''-'' is used as an upload source. Implies [[#nointeractiveinput|''/nointeractiveinput'']]. Streaming is supported with the SFTP and FTP protocols only. |
| Use parameter ''/==nointeractiveinput=='', when feeding commands to ''[[executables|winscp.com]]'' using [[executables#redirection|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. | Use parameter ''/==nointeractiveinput=='', when feeding commands to ''[[executables|winscp.com]]'' using [[executables#redirection|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. | ||
| Line 125: | Line 133: | ||
| Examples: <code batch> | Examples: <code batch> | ||
| winscp.com /script="C:\Users\martin\Documents\myscript.txt" | winscp.com /script="C:\Users\martin\Documents\myscript.txt" | ||
| - | winscp.com /command "open sftp://martin@example.com/ -hostkey=""ssh-rsa 2048 xxxx...=""" "exit" | + | winscp.com /command "open sftp://martin@example.com/ -hostkey=""ssh-rsa 2048 xxxx...""" "exit" |
| winscp.exe /console /script="myscript.txt" /log="myscript.log" | winscp.exe /console /script="myscript.txt" /log="myscript.log" | ||
| </code> | </code> | ||
| Line 142: | Line 150: | ||
| With ''/upload'' parameter WinSCP uploads specified files to initial remote directory of session.((Parameter is primarily intended to allow [[integration#send_to|Windows File Explorer's 'Send To' menu]] integration.)) A dialog to set options is displayed first. | With ''/upload'' parameter WinSCP uploads specified files to initial remote directory of session.((Parameter is primarily intended to allow [[integration#send_to|Windows File Explorer's 'Send To' menu]] integration.)) 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 ''/==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. | + | 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 [[#syntax|// switch]]. | It is recommended to escape the arguments with [[#syntax|// switch]]. | ||
| Line 153: | Line 161: | ||
| ==== [[configuration]] Configuration ==== | ==== [[configuration]] Configuration ==== | ||
| - | With ''/ini'' parameter you may specify [[local_path|local path]] to [[config|configuration INI file]]. It effectively disables using [[config|registry as configuration storage]]. If the file does not exist, default configuration will be used and the file will be created. | + | With ''/ini'' parameter you may specify [[local_path|local path]] to [[config|configuration INI file]]. It effectively disables using registry as [[config|configuration storage]]. If the file does not exist, default configuration will be used and the file will be created. |
| <code batch> | <code batch> | ||
| Line 177: | Line 185: | ||
| ==== [[keygen]] Private key conversion and modification ==== | ==== [[keygen]] Private key conversion and modification ==== | ||
| - | Use the ''/keygen'' switch to convert [[public_key#private|private keys]] from other formats to a PuTTY ''.ppk'' format or to change their passphrase or comment. | + | Use the ''/keygen'' switch to convert [[public_key#private|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 changing a key passphrase or comment). | + | 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. | 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. | ||
| Line 186: | Line 194: | ||
| Use ''/comment'' switch to change the key comment. | 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: | For example, to convert key ''mykey.pem'' from OpenSSH format to ''mykey.ppk'' in PuTTY format and set its comment: | ||
| Line 199: | Line 209: | ||
| </code> | </code> | ||
| - | For a compatibility with *nix ''[[&man_ref(1,puttygen)|puttygen]]'', the ''-o'', ''-P'' and ''-C'' switches are understood as aliases to ''/output'', ''/changepassphrase'' and ''/comment'' respectively. So, for features supported by WinSCP, you can use the same arguments as for ''puttygen'', just prefixed with ''/keygen'': | + | For a compatibility with *nix ''[[https://manpages.debian.org/stable/putty-tools/puttygen.1.en.html|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'': |
| <code batch> | <code batch> | ||
| - | winscp.com /keygen mykey.pem -o mykey.ppk -c "Converted from OpenSSH format" | + | winscp.com /keygen mykey.pem -o mykey.ppk -C "Converted from OpenSSH format" |
| </code> | </code> | ||
| - | |||
| ==== [[auxiliary]] Auxiliary ==== | ==== [[auxiliary]] Auxiliary ==== | ||