A common misconception is that in a batch file, you can paste commands as if you typed them in a console window. So after a line that executes
winscp.com, you can add WinSCP scripting commands. But that’s not possible. The batch file can contain only commands that you can execute on Windows command prompt –
cmd.exe. You cannot directly use sub-commands of those commands (like WinSCP scripting commands).
For example this batch file:
echo Starting WinSCP winscp.com /log=winscp.log /ini=nul open sftp://username:firstname.lastname@example.org/ put d:\examplefile.txt exit echo WinSCP finished
It will execute
winscp.com, entering an interactive WinSCP scripting prompt. Now WinSCP will wait for you to type your commands (WinSCP is not aware of the batch file). On the other hand
cmd.exe (which interprets the batch file), waits for
winscp.com to close, before it even checks the following batch file lines. Only after you close
winscp.com (e.g. by typing WinSCP
cmd.exe will read the line with the
open command. And
cmd.exe will fail executing it, as it does not know any
To execute WinSCP commands in a batch file, you need to use
/scriptswitch, you need to move your WinSCP commands into a separate text file, e.g.
echo Starting WinSCP winscp.com /script=script.txt /log=winscp.log /ini=nul echo WinSCP finished
/commandswitch, you can specify the commands directly on WinSCP command-line. Such command-line tends to be too long. Being in a batch file, you can use use new-line escaping using the caret symbol
^to allow wrapping a long command line to multiple lines for a better readability:
echo Starting WinSCP winscp.com /log=winscp.log /ini=nul /command ^ "open sftp://username:email@example.com/" ^ "put d:\examplefile.txt" ^ "exit" echo WinSCP finished
Many examples on this site (including the one above), as well as batch file template generated by WinSCP, use new-line escaping using the caret symbol
^ to allow wrapping a long command line to multiple lines for a better readability:
winscp.com /log=winscp.log /ini=nul /command ^ "open sftp://username:firstname.lastname@example.org/" ^ "get *" ^ "exit"
When reusing/modifying such script, users frequently find that WinSCP seemingly stops processing the commands in a middle or behaves strangely.
This is commonly caused by an improper syntax of the new-line escaping in the batch file (and as such is not WinSCP issue at all). For the new-line escaping to work as expected in the batch file, the caret symbol
^ has to be the very last character on the line (no spaces after it) and the next line needs to be indented (at least one space at the front).
/command switch, each script command needs to be surrounded by double quotes. As parameters of commands themselves may need to be surrounded by double quotes, those need to be doubled.
For details, see escaping the in-command double-quotes by doubling them.
If your WinSCP command-line contains percent sign, for example to encode special characters in session URL (particularly in the credentials), it may conflict with special meaning of the percent sign in Windows batch files.
You need to double the percent sign to escape it.
For example in the following batch file, the username
username@domain contains the
@ sign. As the
@ sign has a special meaning in the session URL, it needs to be encoded to
%40. But as
% sign has a special meaning in the batch file, it needs to be escaped as
%%, resulting in final
winscp.com /log=winscp.log /ini=nul /command ^ "open sftp://username%%40domain:email@example.com/" ^ "get *" ^ "exit"