Differences
This shows you the differences between the selected revisions of the page.
| scripting 2025-01-26 | scripting 2025-01-26 (current) | ||
| Line 10: | Line 10: | ||
| &screenshotpict(scripting) | &screenshotpict(scripting) | ||
| + | ===== [[using_scripting]] Using Scripting ===== | ||
| + | Enter the console/scripting mode by using ''[[executables|winscp.com]]''; or ''/console'' command-line parameter with ''[[executables|winscp.exe]]''. For details see [[commandline#scripting|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 ''winscp.com''. | ||
| + | The script file must use UTF-8 or UTF-16 (with BOM) encoding. | ||
| + | When running commands specified using ''/script'' or ''/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 ''[[scriptcommand_option#batch|option batch abort]]''. For batch mode it is recommended to turn off confirmations using ''[[scriptcommand_option#confirm|option confirm off]]'' to allow overwrites (otherwise the [[ui_overwrite|overwrite confirmation prompt]] would be answered negatively, making overwrites impossible). | ||
| + | Multiple sessions can be opened simultaneously. Use the ''[[scriptcommand_session|session]]'' command to switch between them. | ||
| + | Note that the first connection to an SSH server requires [[#hostkey|verification of the host key]]. | ||
| + | Also the first connection to FTPS or WebDAVS host with [[tls#certificate|certificate]] signed by untrusted authority requires verification of the certificate. | ||
| + | ~~AD~~ | ||
| + | ===== [[result]] Checking Results ===== | ||
| + | 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 [[logging_xml|XML logging]] useful. | ||
| + | //For more details, refer to [[faq_script_result|*]]// | ||
| + | ===== [[syntax]] Commands Syntax ===== | ||
| + | All WinSCP commands have syntax: | ||
| + | <code> | ||
| + | command -switch -switch2 parameter1 parameter2 ... parametern | ||
| + | </code> | ||
| + | |||
| + | ==== [[quotes]] Command Parameters with Spaces ==== | ||
| + | |||
| + | Command parameters that include space(s) have to be surrounded by double-quotes. To use double-quote literally, double it: | ||
| + | <code winscp> | ||
| + | put "file with spaces and ""quotes"".html" | ||
| + | </code> | ||
| + | |||
| + | Note that when you are specifying commands on [[commandline#scripting|command-line]] using ''/command'', you need to surround each command by double-quote and [[commandline#syntax|escape the in-command double-quotes by doubling them]]. | ||
| + | |||
| + | To debug the quoting, enable session logging on level //Debug 1// (''[[commandline#logging|/loglevel=1]]''). The log will show how WinSCP understands both your command-line and individual scripting commands. | ||
| + | |||
| + | |||
| + | ==== [[variables]] Environment Variables ==== | ||
| + | |||
| + | You can use environment variables in the commands, with syntax ''%NAME%'':((Generally do surround reference by double-quotes to cope properly with spaces in its value.)) | ||
| + | <code winscp> | ||
| + | put "%FILE_TO_UPLOAD%" | ||
| + | </code> | ||
| + | |||
| + | Note that variable expansion is different than in Windows batch files: | ||
| + | |||
| + | * You cannot use any [[https://en.wikibooks.org/wiki/Windows_Batch_Scripting#String_processing|string processing syntax]]. | ||
| + | * You cannot use [[wp>Environment_variable#Windows_2|dynamic/pseudo environment variables]], such as ''%DATE%'' or ''%RANDOM%''. | ||
| + | * References to undefined variables are kept intact (not removed). | ||
| + | * You can use ''%WINSCP_PATH%'' to refer to WinSCP [[executable]] path. | ||
| ==== [[timestamp]] Timestamp ==== | ==== [[timestamp]] Timestamp ==== | ||
| Line 30: | Line 74: | ||
| To use ''<nowiki>%TIMESTAMP...%</nowiki>'' on a command-line in a batch file, you need to escape the ''%'' by doubling it to ''<nowiki>%%TIMESTAMP...%%</nowiki>'', to avoid a batch file interpreter trying to resolve the variable. | To use ''<nowiki>%TIMESTAMP...%</nowiki>'' on a command-line in a batch file, you need to escape the ''%'' by doubling it to ''<nowiki>%%TIMESTAMP...%%</nowiki>'', to avoid a batch file interpreter trying to resolve the variable. | ||
| + | ==== [[arguments]] Script Arguments ==== | ||
| + | You can reference script arguments (passed on command-line using parameter ''[[commandline#scripting|/parameter]]'') using syntax ''%N%'', where ''N'' is ordinal number of argument:((Generally do surround reference by double-quotes to cope properly with spaces in its value.)) | ||
| + | <code winscp> | ||
| + | put "%1%" | ||
| + | </code> | ||
| ==== Case Sensitivity of File Names ==== | ==== Case Sensitivity of File Names ==== | ||