This is an old revision of the document!
Script Commands
- call
- cd
- chmod
- close
- echo
- exit
- get
- help
- keepuptodate
- lcd
- lls
- ln
- lpwd
- ls
- mkdir
- mv
- open
- option
- put
- pwd
- rm
- rmdir
- session
- synchronize
call
With SFTP and SCP protocols, executes arbitrary remote shell command. With FTP protocol, executes a protocol command.
call <command>
With SFTP protocol, that 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
echo
Prints message onto script output. This feature is available only in the latest beta release.
echo <message>
Examples:
echo Uploading all report files...
exit
Closes all sessions and terminates the program.
exit
Alias: bye
get
Downloads one or more files from remote directory to local directory.
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.
Aliases: recv
, mget
Switches:
Switch | Description |
---|---|
-delete |
Delete source remote file(s) after transfer. |
-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
, include
, reconnecttime
XML log elements: download
, rm
(with -delete
)
Examples:
get index.html get -delete index.html about.html .\ get index.html about.html d:\www\ get public_html/index.html d:\www\about.* get *.html *.png d:\www\*.bak
See also synchronize
if you need to transfer modified or non-existing 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 (SFTP and SCP protocols only) |
-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
1 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 index.html about.* mv index.html public_html/about.* mv public_html/index.html public_html/about.html /home/martin/*.bak mv *.html /home/backup/*.bak
open
Establishes new connection.
open <stored_session> open <session_url>
Establishes connection to given host. Use name of the stored session (to open session, stored in folder, use path syntax “folder/session”) or session URL.
Switches:
Switch | Description |
---|---|
-privatekey=<key> |
Private key path |
-timeout=<sec> |
Server response timeout |
-hostkey=“<fingerprint>” |
Specifies fingerprint of expected SSH host key (or several alternative 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=on|off |
Enables passive (=on ) or active (=off ) transfer mode (FTP protocol only). This feature is available only in the latest beta release. |
-implicit |
Implicit TLS/SSL (FTPS protocol only) |
-explicitssl |
Explicit SSL (FTPS protocol only) |
-explicittls |
Explicit TLS (FTPS protocol only) |
-rawsettings setting1=value1 setting2=value2 … |
Allows configuring any session settings using raw format as in an INI file. E.g. to enable SSH compression and agent forwarding use -rawsettings Compression=1 AgentFwd=1 . This feature is available only in the latest beta release. |
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 modifying the options does not change the application configuration.
Options are:
Option | Values and description |
---|---|
echo |
off|on Toggles echoing of command being executed. Commands affected: all |
batch |
off|on|abort|continue Enables batch mode. In batch mode, any choice prompt is automatically replied and any input prompt is cancelled (after short time interval). In batch mode, it is recommended to set confirm to off to allow overwrites. When batch mode is set to on any choice prompt is automatically replied negatively. Unless the prompt has different default answer (such as default “Reconnect” answer for reconnect prompt), in what case the default answer is used (after short time interval). Value abort is like on . In addition, the script is aborted, when any script command fails or any choice prompt is replied with “Abort” answer (or similar). When set to continue any choice prompt is automatically replied with “Skip”, “Ignore” or similar answer. Commands affected: nearly all |
confirm |
off|on 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 a previous value, 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 wildcard1 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. |
-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 (SFTP and SCP protocols only) |
-nopermissions |
Keep default permissions |
-speed=<kibps> |
Limit transfer speed |
Aliases: send
, mput
Effective options: transfer
, confirm
, exclude
, include
, reconnecttime
XML log elements: upload
, chmod
(with -permissions
), touch
(with -preservetime
)
Examples:
put index.html put -delete index.html about.html ./ put -permissions=644 index.html about.html /home/martin/public_html/ put d:\www\index.html about.* 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 index.html about.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 , either (Previous versions used value both ) and none . Ignored for both mode. |
-permissions=<mode> |
Set permissions (SFTP and SCP protocols only) |
-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
- Windows wildcard supports
*
and?
only. It does not support all the features of file masks.Back