WinSCP

https://winscp.net/eng/docs
Admin
WinSCP is a free SFTP, FTP, WebDAV and SCP client for Windows with an easy-to-use graphical...
Tokens:515,237
Snippets:5,294
Trust Score:9.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Create custom WinSCP installer with Inno Setup

Source: https://winscp.net/eng/docs/custom_distribution

Minimal Inno Setup script for a custom WinSCP installer. Sets application metadata, installs WinSCP.exe and DragExt.dll, creates Start menu and desktop icons, configures Explorer interface and drag-and-drop extension via registry, offers to launch WinSCP after install, and offers configuration cleanup on uninstall. Full script is in deployment/winscpsetup.iss in the source code.

```ini
[Setup]
; Name of the application
AppName=WinSCP (provided by Some Company)
; Name of the application including version
AppVerName=WinSCP 5.0
; Installation directory (can be changed by user)
DefaultDirName={pf}\WinSCP
; Start menu group name
DefaultGroupName=WinSCP (provided by Some Company)
; Not to allow installation while WinSCP is running
AppMutex=WinSCP
 
[Files]
; Install WinSCP itself
Source: "WinSCP.exe"; DestDir: "{app}"; \
  Flags: ignoreversion
; It is recommended (especially for not experienced users) to install
; drag&drop shell extension
Source: "DragExt.dll"; DestDir: "{app}"; \
  Flags: regserver restartreplace uninsrestartdelete
 
[Icons]
; Start menu icon
Name: "{group}\WinSCP"; Filename: "{app}\WinSCP.exe"
; Desktop icon
Name: "{userdesktop}\WinSCP"; Filename: "{app}\WinSCP.exe"
 
[Registry]
#define RegistryKey "Software\Martin Prikryl\WinSCP 2"
; Make Explorer interface initial setting
; (recommended especially for not experienced users)
; Remove or use value 0 for Commander interface
Root: HKCU; SubKey: "{#RegistryKey}\Configuration\Interface"; ValueType: dword; \
  ValueName: "Interface"; ValueData: 1
; Enable using of drag&drop shell extension
; (and make sure it is disabled again when the extension is uninstalled)
Root: HKCU; SubKey: "{#RegistryKey}\Configuration\Interface"; ValueType: dword; \
  ValueName: "DDExtEnabled"; ValueData: 1; \
  Flags: uninsdeletevalue
 
[Run]
; Offer starting WinSCP after installation
Filename: "{app}\WinSCP.exe"; Description: "Launch &WinSCP"; \
  Flags: nowait postinstall skipifsilent
 
[UninstallRun]
; Offer configuration cleanup on uninstallation
Filename: "{app}\WinSCP.exe"; Parameters: "/UninstallCleanup"; \
  RunOnceId: "UninstallCleanup"
```

--------------------------------

### Start WinSCP process with winscp.com

Source: https://winscp.net/eng/docs/guide_dotnet

Initializes a Process object for winscp.com with no window and starts it. Use this as the base setup before configuring input/output redirection or arguments.

```csharp
Process winscp = new Process();
winscp.StartInfo.FileName = "winscp.com";
winscp.StartInfo.UseShellExecute = false;
winscp.StartInfo.CreateNoWindow = true;
winscp.Start();
```

--------------------------------

### mkdir command example

Source: https://winscp.net/eng/docs/scriptcommand_mkdir

Example that creates the remote directory public_html.

```WinSCP script
mkdir public_html
```

--------------------------------

### Compile installer script with iscc

Source: https://winscp.net/eng/docs/custom_distribution

Compile the installer script with Inno Setup compiler. Save the script as winscpsetup.iss and place WinSCP.exe and DragExt.dll in the same directory before running.

```text
iscc winscpsetup.iss

```

--------------------------------

### open command examples

Source: https://winscp.net/eng/docs/scriptcommand_open

Examples of the 'open' command for various protocols and options, including SFTP, SCP, FTPS, and FTP.

```text
open sftp://martin:mypassword@example.com/ -hostkey="ssh-rsa 2048 xxxxxxxxxxx..."
```

```text
open scp://test@example.com:2222/ -privatekey=mykey.ppk
```

```text
open ftps://martin:mypassword@example.com/ -implicit -certificate="xx:xx:xx:xx:xx:xx:xx:xx..."
```

```text
open sftp://martin:mypassword@example.com/ -rawsettings ProxyMethod=3 ProxyHost=proxy
```

```text
open sftp://martin@example.com/
```

```text
open sftp://example.com/
```

```text
open ftp://martin:mypassword@example.com/
```

--------------------------------

### Scripting example: cd and get with relative paths

Source: https://winscp.net/eng/docs/library_from_script

Shows a WinSCP script that changes remote and local directories before downloading a file. Use this as a reference for scripting mode syntax.

```text
cd /home/martinp
lcd d:\
get test.txt

```

--------------------------------

### Run PHP example script

Source: https://winscp.net/eng/docs/guide_automation_advanced

Executes the PHP example script with the PHP CLI interpreter.

```batch
php.exe example.php
```

--------------------------------

### call gzip example

Source: https://winscp.net/eng/docs/scriptcommand_call

Compresses the previously created SQL dump file using gzip. This is a separate command from the mysqldump example.

```plaintext
call gzip -c all_databases.sql > all_databases.gz

```

--------------------------------

### Download and upload file with WinSCP script

Source: https://winscp.net/eng/docs/scripting

Connects to example.com as user, downloads examplefile.txt to d:\, then reconnects as user2 and uploads the file back. Save this script to example.txt and run it with winscp.com /ini=nul /script=example.txt.

```WinSCP script
# Connect
open sftp://user:password@example.com/ -hostkey="ssh-rsa 2048 xxxxxxxxxxx..."
# Change remote directory
cd /home/user
# Download file to the local directory d:\
get examplefile.txt d:\
# Disconnect
close
# Connect as a different user
open sftp://user2:password@example.com/
# Change the remote directory
cd /home/user2
# Upload the file to current working directory
put d:\examplefile.txt 
# Disconnect
close
# Exit WinSCP
exit
```

--------------------------------

### PuTTY Session Startup Command for Bash

Source: https://winscp.net/eng/docs/integration_putty

Example command to change to the current remote directory before starting a bash login shell.

```bash
cd "!/" ; /bin/bash --login
```

--------------------------------

### download operation example

Source: https://winscp.net/eng/docs/logging_xml

Example of the `download` operation element, which represents downloading a single file. It includes `filename`, `destination`, and `size` child elements. The `result` child element is always present. Associated script commands: `get`, `synchronize local|both`.

```xml
<download>
  <filename value="/home/martin/public_html/about.html" />
  <destination value="d:\www\about.htm" />
  <size value="55387" />
  <result success="true" />
</download>
```

--------------------------------

### ls command examples

Source: https://winscp.net/eng/docs/scriptcommand_ls

Examples of using the `ls` command: listing files matching a wildcard, listing a specific directory, listing the working directory, and listing files in a directory with a wildcard.

```text
ls *.html

```

```text
ls /home/martin

```

```text
ls

```

```text
ls /home/martin/*.html

```

--------------------------------

### C# .NET assembly: SessionOptions.RootPath

Source: https://winscp.net/eng/docs/faq_root_path

C# example for the .NET assembly. Use `SessionOptions.RootPath` to set the starting folder when the server does not allow access to the root path.

```csharp
SessionOptions sessionOptions = new SessionOptions
{
    Protocol = Protocol.Webdav,
    HostName = "www.example.com",
    RootPath = "/dav",
    ...
};
```

--------------------------------

### rm XML element example

Source: https://winscp.net/eng/docs/logging_xml

Example of the `rm` XML element returned by the scripting commands `get -delete`, `keepuptodate -delete`, `rm`, `rmdir`, and `synchronize local|both -delete`. It deletes a remote file or directory; the optional `recursive` attribute indicates recursive deletion with SCP protocol.

```xml
<rm recursive="true">
  <filename value="/home/martin/public_html/images" />
  <result success="true" />
</rm>
```

--------------------------------

### WinSCP session opening examples

Source: https://winscp.net/eng/docs/commandline

Examples of opening a saved site, an SFTP session with a host key fingerprint, an SCP session with a private key, and an FTPS session. The /hostkey parameter accepts the fingerprint of the expected SSH host key.

```text
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/
```

--------------------------------

### help put example

Source: https://winscp.net/eng/docs/scriptcommand_help

Displays help for the 'put' command.

```plaintext
help put
```

--------------------------------

### Convert ascii get to -transfer=ascii

Source: https://winscp.net/eng/docs/guide_ftp_script_to_sftp

Convert ftp.exe 'ascii' followed by 'get' to WinSCP's get command with -transfer=ascii switch.

```plaintext
ascii
get index.html

```

```plaintext
get -transfer=ascii index.html
```

--------------------------------

### Full C# Example: Run WinSCP and Parse XML Log

Source: https://winscp.net/eng/docs/guide_dotnet

Complete C# example that launches WinSCP.com hidden, sends scripting commands via standard input, waits for exit, and parses the XML log to check for errors or list files. Requires the WinSCP .NET assembly and a configured session 'mysession'. The log file may not exist on fatal failure.

```csharp
using System;
using System.Diagnostics;
using System.Xml;
using System.Xml.XPath;
 
...
 
const string logname = "log.xml";
 
// Run hidden WinSCP process
Process winscp = new Process();
winscp.StartInfo.FileName = "winscp.com";
winscp.StartInfo.Arguments = "/xmllog=\"" + logname + "\"";
winscp.StartInfo.UseShellExecute = false;
winscp.StartInfo.RedirectStandardInput = true;
winscp.StartInfo.RedirectStandardOutput = true;
winscp.StartInfo.CreateNoWindow = true;
winscp.Start();
 
// Feed in the scripting commands
winscp.StandardInput.WriteLine("option batch abort");
winscp.StandardInput.WriteLine("option confirm off");
winscp.StandardInput.WriteLine("open mysession");
winscp.StandardInput.WriteLine("ls");
winscp.StandardInput.WriteLine("put d:\\examplefile.txt");
winscp.StandardInput.Close();
 
// Collect all output (not used in this example)
string output = winscp.StandardOutput.ReadToEnd();
 
// Wait until WinSCP finishes
winscp.WaitForExit();
 
// Parse and interpret the XML log
// (Note that in case of fatal failure the log file may not exist at all)
XPathDocument log = new XPathDocument(logname);
XmlNamespaceManager ns = new XmlNamespaceManager(new NameTable());
ns.AddNamespace("w", "http://winscp.net/schema/session/1.0");
XPathNavigator nav = log.CreateNavigator();
 
// Success (0) or error?
if (winscp.ExitCode != 0)
{
    Console.WriteLine("Error occured");
 
    // See if there are any messages associated with the error
    foreach (XPathNavigator message in nav.Select("//w:message", ns))
    {
        Console.WriteLine(message.Value);
    }
}
else
{
    // It can be worth looking for directory listing even in case of
    // error as possibly only upload may fail
    
    XPathNodeIterator files = nav.Select("//w:file", ns);
    Console.WriteLine("There are {0} files and subdirectories:", files.Count);
    foreach (XPathNavigator file in files)
    {
        Console.WriteLine(file.SelectSingleNode("w:filename/@value", ns).Value);
    }
}
```

--------------------------------

### WinSCP script: full example with connection and download

Source: https://winscp.net/eng/docs/library_from_script

Complete script that connects via SFTP, changes directory, forces binary mode, downloads a file, and disconnects. Use as a base for scripting automation.

```text
# Connect
open sftp://user:password@example.com/ -hostkey="ssh-rsa 2048 xxxxxxxxxxx..."
# Change remote directory
cd /home/user
# Force binary mode transfer
option transfer binary
# Download file to the local directory d:\
get examplefile.txt d:\
# Disconnect
close
# Exit WinSCP
exit

```

--------------------------------

### Run WinSCP script file with /script=example.txt

Source: https://winscp.net/eng/docs/script_upload_single_file

Run the saved script file (example.txt) using winscp.com with the /script parameter.

```plaintext
winscp.com /script=example.txt
```

--------------------------------

### lcd command example

Source: https://winscp.net/eng/docs/scriptcommand_lcd

Example usage of the lcd command to change the local working directory to d:\.

```plaintext
lcd d:\
```
Tokens:
Raw