Skip to main content

How to Automate WinSCP Transfers from a Batch Script

WinSCP is a powerful, open-source file transfer client for Windows. While it offers a graphical interface for drag-and-drop FTP, SFTP, and WebDAV, its true strength lies in its robust command-line interface. For corporate environments requiring strict protocol handling and password-based SFTP (which the native OpenSSH client does not easily automate in Batch), WinSCP is the standard solution.

In this guide, we will demonstrate how to automate complex remote file transfers using WinSCP from a Batch script.

The Strategy: The WinSCP.com Executable​

Unlike WinSCP.exe (which launches the GUI window), the WinSCP.com executable operates purely as a console utility. In a Batch script, you use it with the /command parameter to establish a session, perform operations, and disconnect cleanly.

Method 1: The One-Liner Connection (Basic Pull)​

Downloading a daily data dump from a password-secured SFTP server requires minimal syntax.

@echo off
setlocal

:: Define the WinSCP console executable
set "winScpExe=C:\Program Files (x86)\WinSCP\WinSCP.com"

:: Validate WinSCP is installed
if not exist "%winScpExe%" (
    echo [ERROR] WinSCP not found at "%winScpExe%".
    pause
    exit /b 1
)

:: Define connection and file details
set "sftpHost=sftp.example.com"
set "remotePath=/var/backups/DailyDump.zip"
set "localPath=C:\Backups\DailyDump.zip"

:: Ensure the local destination directory exists
for %%A in ("%localPath%") do (
    if not exist "%%~dpA" mkdir "%%~dpA"
)

:: Prompt for credentials so they are not stored in plain text
set /p "sftpUser=Enter SFTP username: "
set /p "sftpPass=Enter SFTP password: "

if "%sftpUser%"=="" (
    echo [ERROR] Username cannot be empty.
    pause
    exit /b 1
)
if "%sftpPass%"=="" (
    echo [ERROR] Password cannot be empty.
    pause
    exit /b 1
)

echo.
echo Starting Automated SFTP Download...
echo.

:: The /command parameter feeds a sequence of operations
:: The caret (^) allows splitting the command across multiple lines
:: /ini=nul prevents WinSCP from saving session data to a configuration file
:: Replace the -hostkey value with the server's actual fingerprint in production
"%winScpExe%" /ini=nul /command ^
    "option batch abort" ^
    "option confirm off" ^
    "open sftp://%sftpUser%:%sftpPass%@%sftpHost%/ -hostkey=""*""" ^
    "get %remotePath% %localPath%" ^
    "exit"

if %errorlevel% equ 0 (
    echo.
    echo ==========================================
    echo TRANSFER SUCCESSFUL
    echo ==========================================
) else (
    echo.
    echo [ERROR] WinSCP returned error code: %errorlevel%.
    pause
    exit /b %errorlevel%
)

pause
endlocal
warning

Setting -hostkey="*" accepts any host key, leaving the connection vulnerable to Man-In-The-Middle attacks. For production scripts, connect to the server once using the WinSCP GUI, verify the host key, and copy the exact fingerprint into the -hostkey="ssh-rsa 2048 xx:yy:zz:..." argument.

Method 2: Supplying a Dedicated Script File​

For complex operations (such as synchronizing an entire directory or uploading hundreds of files), stringing commands directly via ^ becomes unreadable. WinSCP interprets .txt script files using the /script= parameter.

By passing the session URL directly on the WinSCP command line, the connection opens before the script executes. This keeps credentials out of the script file entirely.

1. Create sync_script.txt​

# Ensure Batch mode (disables interactive prompts)
option batch abort
# Disable overwrite confirmations
option confirm off

# Change local directory
lcd "C:\Project\WebsiteData"

# Change remote directory
cd "/var/www/html/assets"

# Force a Mirror Synchronization (Local is the master, Remote is the mirror)
# "remote" pushes changes to the server. "local" pulls changes from the server.
synchronize remote

# Disconnect
exit

2. Implementation Script (Batch File)​

@echo off
setlocal

set "winScpExe=C:\Program Files (x86)\WinSCP\WinSCP.com"
set "winScpScript=C:\Scripts\sync_script.txt"
set "logFile=C:\Scripts\sync_log.txt"

:: Connection details
set "ftpHost=ftp.company.com"

:: Check if WinSCP is installed
if not exist "%winScpExe%" (
    echo [ERROR] WinSCP not found at "%winScpExe%".
    pause
    exit /b 1
)

:: Check if the script file exists
if not exist "%winScpScript%" (
    echo [ERROR] WinSCP script not found at "%winScpScript%".
    pause
    exit /b 1
)

:: Prompt for credentials so they are not stored in the script file
set /p "ftpUser=Enter FTP username: "
set /p "ftpPass=Enter FTP password: "

if "%ftpUser%"=="" (
    echo [ERROR] Username cannot be empty.
    pause
    exit /b 1
)

echo Launching WinSCP Synchronization...
echo.

:: The session URL on the command line opens the connection before the script runs
:: This keeps credentials out of the script file entirely
:: /ini=nul prevents WinSCP from saving session data
:: /log records the full session handshake for debugging
:: Replace -certificate with the server's actual fingerprint in production
"%winScpExe%" /ini=nul /script="%winScpScript%" /log="%logFile%" ^
    "ftps://%ftpUser%:%ftpPass%@%ftpHost%/ -implicit -certificate=""*"""

if %errorlevel% equ 0 (
    echo.
    echo ==========================================
    echo SYNCHRONIZATION SUCCESSFUL
    echo ==========================================
) else (
    echo.
    echo [ERROR] WinSCP returned error code: %errorlevel%.
    echo Review the log file: "%logFile%"
    pause
    exit /b %errorlevel%
)

pause
endlocal
tip

WinSCP.com (the console executable) waits synchronously, allowing Batch to correctly check %errorlevel% for success or failure. If you call WinSCP.exe instead, the GUI launches in the background and the Batch script continues immediately, making error detection impossible.

Why Automate WinSCP Transfers?​

  1. SFTP with Password Authentication: The native Windows OpenSSH client prompts interactively for passwords, making it difficult to automate in Batch scripts. WinSCP handles password-based SFTP sessions cleanly through its scripting interface.
  2. WebDAV and S3 Support: WinSCP handles Amazon S3 buckets and corporate WebDAV libraries using the same scripting syntax as standard FTP.
  3. Advanced Synchronization: The synchronize command automatically diffs directory structures and transfers only modified files, rather than copying entire directory trees every night.

Important Considerations​

  1. Host Key and Certificate Verification: Setting -hostkey="*" or -certificate="*" bypasses server identity verification, leaving connections vulnerable to Man-In-The-Middle attacks. The graphical WinSCP client can generate the exact fingerprint string for your production scripts.
  2. WinSCP.exe vs WinSCP.com: Calling .com waits synchronously, allowing Batch to correctly use %errorlevel% checks. If you call .exe, the GUI application launches in the background and your Batch script loses the ability to detect transfer failures.
  3. Interactive Prompts: Always include option batch abort and option confirm off at the start of your transfer sequence. Without these, the WinSCP console will hang indefinitely waiting for manual input when it encounters an overwrite confirmation or connection warning.

Conclusion​

Interfacing with WinSCP converts a purely local automation task into a network-spanning operation. By wrapping WinSCP.com parameters in a Batch script, you standardize complex FTP, S3, and SFTP transfers inside readable, maintainable script structures, enabling reliable remote file management across your infrastructure.

Table of Contents