This is an old revision of the document!

# Script Commands

In its scripting functionality, WinSCP supports set of commands described below.

You can see the very same help for the commands as shown here, if you type command `help <command>` directly in console.

## General Syntax

Command parameters that include space(s) have to be enclosed in double-quotes. To use double-quote literally, double it:

`put "file with spaces and ""quotes"".html"`

You can use environment variables in the commands, with syntax `%NAME%`1:

`put "%FILE_TO_UPLOAD%"`

You can reference script arguments (passed on command-line using parameter `/parameter`) using syntax `%N%`, where `N` is ordinal number of argument1:

`put "%1%"`

Note that WinSCP treats filenames in case sensitive manner. So even if your server treats filenames in case insensitive manner, make sure you specify case properly2.

## call

With SFTP and SCP protocols, executes arbitrary remote shell command. With FTP protocol, executes a protocol command.

```call <command>
```

If current session does not allow execution of arbitrary remote command separate shell session will be automatically opened.

The command must not require user input.

Alias: `!`

XML Log Element: `call`

Examples:

```call mysqldump --opt -u USERNAME --password=PASSWORD --all-databases > all_databases.sql
call gzip -c all_databases.sql > all_databases.gz```

## cd

Changes remote working directory for active session.

```cd [ <directory> ]
```

If `directory` is not specified, changes to home directory.

Examples:

```cd /home/martin
cd```

## chmod

Changes permissions of one or more remote files.

```chmod <mode> <file> [ <file2> ... ]
```

`mode` can be specified as three or four-digit octal number.

Filename can be replaced with wildcard to select multiple files.

XML Log Element: `chmod`

Examples:

```chmod 644 index.html about.html
chmod 1700 /home/martin/public_html
chmod 644 *.html```

## close

Closes session.

```close [ <session> ]
```

Closes session specified by its number. When `session` is not specified, closes currently selected session.

Examples:

```close 1
close```

## exit

Closes all sessions and terminates the program.

```exit
```

Alias: `bye`

## get

```get <file> [ [ <file2> ... ] <directory>\[ <newname> ] ]
```

Downloads one or more files from remote directory to local directory. If only one parameter is specified downloads the file to local working directory. If more parameters are specified, all except the last one specify set of files to download. The last parameter specifies target local directory and optionally operation mask to store file(s) under different name. Destination directory must end with backslash. Filename can be replaced with wildcard to select multiple files. To download more files to current working directory use `.\` as the last parameter.

Use option command to set transfer options.

Alias: `recv`

Switches:

Switch Description
`-delete` Delete source remote file(s) after transfer. Options `exclude` and `include` are ignored.
`-resume` Automatically resume transfer if possible (SFTP and FTP protocols only). Cannot be combined with `-append`.
`-append` Append source file to the end of target file (SFTP protocol only). Cannot be combined with `-resume`.
`-preservetime` Preserve timestamp
`-nopreservetime` Do not preserve timestamp
`-speed=<kibps>` Limit transfer speed

Effective options: `transfer`, `confirm`, `exclude` (not with `-delete`), `include` (not with `-delete`), `reconnecttime`

XML Log Elements: `download`, `rm` (with `-delete`)

Examples:

```get index.html
get *.html *.png d:\www\*.bak```

See also `synchronize` if you need to transfer modified files only.

## help

Displays help for script commands.

```help [ <command> [ <command2> ... ] ]
```

Displays list of commands when no parameters are specified. Displays help for each command when some are specified.

Alias: `man`

Examples:

```help ls
help```

## keepuptodate

Watches for changes in local directory and reflects them on remote one.

```keepuptodate [ <local directory> [ <remote directory> ] ]
```

When directories are not specified, current working directories are synchronized. To stop watching for changes press `Ctrl-C`.

Note: Overwrite confirmations are always off for the command.

Switches:

Switch Description
`-delete` Delete obsolete files
`-permissions=<mode>` Set permissions
`-nopermissions` Keep default permissions
`-speed=<kibps>` Limit transfer speed

Effective options: `transfer`, `exclude`, `include`, `reconnecttime`

XML Log Elements: `upload`, `touch`, `chmod` (with `-permissions`), `rm` (with `-delete`)

Examples:

```keepuptodate -delete
keepuptodate d:\www /home/martin/public_html```

## lcd

Changes local working directory for all sessions.

```lcd <directory>
```

Example:

`lcd d:\`

## lls

Lists the contents of local directory.

```lls [ <directory> ]\[ <wildcard> ]
```

If `directory` is not specified, lists working directory. When `wildcard` is specified, it is treated as set of files to list. Otherwise, all files are listed.

Examples:

```lls *.html
lls d:\
lls```

## ln

```ln <target> <symlink>
```

Alias: `symlink`

Example:

`ln /home/martin/public_html www`

## lpwd

Prints current local working directory (valid for all sessions).

```lpwd
```

## ls

Lists the contents of specified directory.

```ls [ <directory> ]/[ <wildcard> ]
```

Lists the contents of specified remote directory. If `directory` is not specified, lists working directory. When `wildcard`3 is specified, it is treated as set of files to list. Otherwise, all files are listed.

Alias: `dir`

XML Log Element: `ls`

Examples:

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

## mkdir

```mkdir <directory>
```

XML Log Element: `mkdir`

Example:

`mkdir public_html`

## mv

Moves or renames one or more remote files.

```mv <file> [ <file2> ... ] [ <directory>/ ][ <newname> ]
```

Destination `directory` or `newname` or both must be specified. Destination directory must end with slash. Operation mask can be used instead of new name. Filename can be replaced with wildcard to select multiple files.

Alias: `rename`

XML Log Element: `mv`

Examples:

```mv index.html public_html/
mv *.html /home/backup/*.bak```

## open

Establishes new connection.

```open <stored session>
open [ sftp|ftp|scp:// ][ <user> [ :password ] @ ] <host> [ :<port> ]
```

Establishes connection to given host. Use name of the stored session (to open session, stored in folder, use path syntax “folder/session”). You can also specify `host`, `username`, `port` and protocol directly.

Switches:

Switch Description
`-privatekey=<key>` Private key path
`-timeout=<sec>` Server response timeout
`-hostkey=“<fingerprint>”` Specifies fingerprint of expected SSH host key (or several fingerprints separated by semicolon). It makes WinSCP automatically accept hostkey with the fingerprint. As the hostkey fingerprint contains spaces you need to enclose it in quotes. SFTP and SCP protocols only.
`-certificate=“<fingerprint>”` Specifies fingerprint of expected SSL/TLS sertificate (or several fingerprints separated by semicolon). It makes WinSCP automatically accept certificate with the fingerprint. FTPS protocol only.
`-passive` Passive mode (FTP protocol only)
`-implicit` Implicit TLS/SSL (FTPS protocol only)
`-explicitssl` Explicit SSL (FTPS protocol only)
`-explicittls` Explicit TLS (FTPS protocol only)

XML Log Element: `session`

Examples:

```open sftp://martin@example.com -hostkey="ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
open scp://test@example.com:2222 -privatekey=mykey.ppk
open ftps://martin@example.com -implicit -certificate="xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
open martin@example.com
open example.com
open```

## option

Shows or sets value of script options.

```option [ <option> [ <value> ] ]
```

If no parameters are specified, lists all script options and their values. When one parameter is specified only, shows value of the option. When two parameters are specified sets value of the option. Initial values of some options are taken from application configuration, however modifing the options does not change the application configuration.

Options are:

Option Values and description
`echo` `on|off`
Toggles echoing of command being executed.
Commands affected: all
`batch` `on|off|abort|continue`
Toggles batch mode (all prompts are automatically replied negatively). When `on`, it is recommended to set `confirm` to `off` to allow overwrites. With `abort` script is aborted when any error occurs. With `continue` all errors are ignored.
Commands affected: nearly all
`confirm` `on|off`
Toggles confirmations (overwrite, etc.).
Commands affected: `get`, `put`
`transfer` `binary|ascii|automatic`
Transfer mode: binary, ascii (text), automatic (by extension).
Commands affected: `get`, `put`, `synchronize`, `keepuptodate`
`exclude`
`include`
`clear | <mask>[;<mask2>...]`
Sets exclusion or inclusion masks (only one can be set at time).
Commands affected: `get`, `put`, `synchronize`, `keepuptodate`
`reconnecttime` `off | <sec>`
Sets time limit in seconds to try reconnecting broken sessions.
Commands affected: `get`, `put`, `synchronize`, `keepuptodate`

Aliases: `ascii` (for `option transfer ascii`), `binary` (for `option transfer binary`)

Examples:

```option transfer
option confirm off
option include "*.html; */"
option exclude "*.tpl.php"
option exclude "*.mp3; *.mp4; *.lnk; *.exe; *.msi; My Pictures; My Music; My Videos;"
option```

Note that resetting the same option overwrites previous values, it does not append.

## put

Uploads one or more files from local directory to remote directory.

```put <file> [ [ <file2> ... ] <directory>/[ <newname> ] ]
```

If only one parameter is specified uploads the file to remote working directory. If more parameters are specified, all except the last one specify set of files to upload. The last parameter specifies target remote directory and optionally operation mask to store file(s) under different name. Destination directory must end with slash. Filename can be replaced with Windows wildcard3 to select multiple files. To upload more files to current working directory use `./` as the last parameter.

Use option command to set transfer options.

Switches:

Switch Description
`-delete` Delete source local file(s) after transfer. Options `exclude` and `include` are ignored.
`-resume` Automatically resume transfer if possible (SFTP and FTP protocols only). Cannot be combined with `-append`.
`-append` Append source file to the end of target file (SFTP protocol only). Cannot be combined with `-resume`.
`-preservetime` Preserve timestamp
`-nopreservetime` Do not preserve timestamp
`-permissions=<mode>` Set permissions
`-nopermissions` Keep default permissions
`-speed=<kibps>` Limit transfer speed

Alias: `send`

Effective options: `transfer`, `confirm`, `exclude` (not with `-delete`), `include` (not with `-delete`), `reconnecttime`

XML Log Elements: `upload`, `chmod` (with `-permissions`), `touch` (with `-preservetime`)

Examples:

```put index.html
put *.html *.png /home/martin/backup/*.bak```

See also `synchronize` if you need to transfer modified files only.

## pwd

Prints current remote working directory for active session.

```pwd
```

## rm

Removes one or more remote files.

```rm <file> [ <file2> ... ]
```

If remote recycle bin is configured, moves file to the bin instead of deleting it. Filename can be replaced with wildcard to select multiple files.

XML Log Element: `rm`

Examples:

```rm index.html
rm *.html```

## rmdir

Removes one or more remote directories.

```rmdir <directory> [ <directory2> ... ]
```

If remote recycle bin is configured, moves directory to the bin instead of deleting it.

XML Log Element: `rm`

Example:

`rmdir public_html`

## session

Manages opened sessions.

```session [ <session> ]
```

Makes session specified by its number active. When session number is not specified, lists connected sessions.

Examples:

```session 1
session```

## synchronize

```synchronize local|remote|both [ <local directory> [ <remote directory> ] ]
```

When the first parameter is `local`, changes from remote directory are applied to local directory. When the first parameter is `remote`, changes from the local directory are applied to the remote directory. When the first parameter is `both`, both local and remote directories can be modified.

When directories are not specified, current working directories are synchronized.

Note: Overwrite confirmations are always off for the command.

Switches:

Switch Description
`-delete` Delete obsolete files. Ignored for `both`.
`-mirror` Mirror mode (synchronize also older files). Ignored for `both`.
`-criteria=<criteria>` Comparison criteria. Possible values are `time`, `size`, `both` and `none`. Ignored for `both` mode.
`-permissions=<mode>` Set permissions
`-nopermissions` Keep default permissions
`-speed=<kibps>` Limit transfer speed

Effective options: `transfer`, `exclude`, `include`, `reconnecttime`

XML Log Elements: `download` (with `local` or `both`), `upload` (with `remote` or `both`), `touch` (with `remote` or `both`), `chmod` (with `remote` or `both` and `-permissions`), `rm` (with `remote` and `-delete`)

Examples:

```synchronize remote -delete
synchronize both d:\www /home/martin/public_html```
1. Generally do enclose reference to double-quotes to cope properly with spaces in its value.Back
2. This is important particularly for FTP sessions.Back
3. Windows wildcard supports `*` and `?` only. It does not support all the features of file masks.Back