Differences
This shows you the differences between the selected revisions of the page.
| scriptcommands 2011-11-10 | scriptcommands (current) | ||
| Line 1: | Line 1: | ||
| - | ====== Script Commands ====== | ||
| - | ~~NOINDEX~~ | ||
| - | |||
| - | ===== call ===== | ||
| - | With [[protocols|SFTP and SCP protocols]], executes arbitrary [[remote_command|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: ''[[logging_xml#call|call]]'' | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | call mysqldump --opt -u USERNAME --password=PASSWORD --all-databases > all_databases.sql | ||
| - | call gzip -c all_databases.sql > all_databases.gz | ||
| - | </code> | ||
| - | |||
| - | ===== cd ===== | ||
| - | Changes remote working directory for active session. | ||
| - | |||
| - | cd [ <directory> ] | ||
| - | |||
| - | If ''directory'' is not specified, changes to home directory. | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | cd /home/martin | ||
| - | cd | ||
| - | </code> | ||
| - | |||
| - | ===== chmod ===== | ||
| - | [[task_properties|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 [[file_mask|wildcard]] to select multiple files. | ||
| - | |||
| - | XML log element: ''[[logging_xml#chmod|chmod]]'' | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | chmod 644 index.html about.html | ||
| - | chmod 1700 /home/martin/public_html | ||
| - | chmod 644 *.html | ||
| - | </code> | ||
| - | |||
| - | ===== close ===== | ||
| - | Closes session. | ||
| - | |||
| - | close [ <session> ] | ||
| - | |||
| - | Closes session specified by its number. When ''session'' is not specified, closes currently selected session. | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | close 1 | ||
| - | close | ||
| - | </code> | ||
| - | |||
| - | ===== echo ===== | ||
| - | Prints message onto script output. &beta_feature | ||
| - | |||
| - | echo <message> | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | echo Uploading all report files... | ||
| - | </code> | ||
| - | |||
| - | ===== exit ===== | ||
| - | Closes all sessions and terminates the program. | ||
| - | |||
| - | exit | ||
| - | |||
| - | Alias: ''bye'' | ||
| - | |||
| - | ===== get ===== | ||
| - | [[task_download|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|operation mask]] to store file(s) under different name. Destination directory must end with backslash. Filename can be replaced with [[file_mask|wildcard]] to select multiple files. To download more files to current working directory use ''.\'' as the last parameter. | ||
| - | |||
| - | Use [[scriptcommand_option|option]] command to set [[transfer_settings|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|SFTP protocol]] only). Cannot be combined with ''-resume''. | | ||
| - | | ''-preservetime'' | Preserve timestamp | | ||
| - | | ''-nopreservetime'' | Do not preserve timestamp | | ||
| - | | ''-speed=<kibps>'' | Limit transfer speed | | ||
| - | |||
| - | Effective [[scriptcommand_option|options]]: ''transfer'', ''confirm'', ''exclude'', ''include'', ''reconnecttime'' | ||
| - | |||
| - | XML log elements: ''[[logging_xml#download|download]]'', ''[[logging_xml#rm|rm]]'' (with ''-delete'') | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | 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 | ||
| - | </code> | ||
| - | |||
| - | See also ''[[scriptcommand_synchronize|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: | ||
| - | <code winscp> | ||
| - | help ls | ||
| - | help | ||
| - | </code> | ||
| - | |||
| - | ===== keepuptodate ===== | ||
| - | [[task_keep_up_to_date|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 [[scriptcommand_option|options]]: ''transfer'', ''exclude'', ''include'', ''reconnecttime'' | ||
| - | |||
| - | XML log elements: ''[[logging_xml#upload|upload]]'', ''[[logging_xml#touch|touch]]'', ''[[logging_xml#chmod|chmod]]'' (with ''-permissions''), ''[[logging_xml#rm|rm]]'' (with ''-delete'') | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | keepuptodate -delete | ||
| - | keepuptodate d:\www /home/martin/public_html | ||
| - | </code> | ||
| - | |||
| - | |||
| - | ===== lcd ===== | ||
| - | Changes local working directory for all sessions. | ||
| - | |||
| - | lcd <directory> | ||
| - | |||
| - | Example: | ||
| - | <code winscp> | ||
| - | lcd d:\ | ||
| - | </code> | ||
| - | |||
| - | ===== lls ===== | ||
| - | Lists the contents of local directory. | ||
| - | |||
| - | lls [ <directory> ]\[ <wildcard> ] | ||
| - | |||
| - | If ''directory'' is not specified, lists working directory. When ''[[file_mask|wildcard]]'' is specified, it is treated as set of files to list. Otherwise, all files are listed. | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | lls *.html | ||
| - | lls d:\ | ||
| - | lls | ||
| - | </code> | ||
| - | |||
| - | ===== ln ===== | ||
| - | [[task_link|Creates remote symlink]]. | ||
| - | |||
| - | ln <target> <symlink> | ||
| - | |||
| - | Alias: ''symlink'' | ||
| - | |||
| - | Example: | ||
| - | <code winscp> | ||
| - | ln /home/martin/public_html www | ||
| - | </code> | ||
| - | |||
| - | ===== 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'' ((Windows wildcard supports ''*'' and ''?'' only. It does not support all the features of [[file_mask|file masks]].)) is specified, it is treated as set of files to list. Otherwise, all files are listed. | ||
| - | |||
| - | Alias: ''dir'' | ||
| - | |||
| - | XML log element: ''[[logging_xml#ls|ls]]'' | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | ls *.html | ||
| - | ls /home/martin | ||
| - | ls | ||
| - | </code> | ||
| - | |||
| - | ===== mkdir ===== | ||
| - | [[task_create_directory|Creates remote directory]]. | ||
| - | |||
| - | mkdir <directory> | ||
| - | |||
| - | XML log element: ''[[logging_xml#mkdir|mkdir]]'' | ||
| - | |||
| - | Example: | ||
| - | <code winscp> | ||
| - | mkdir public_html | ||
| - | </code> | ||
| - | |||
| - | ===== mv ===== | ||
| - | [[task_move_duplicate|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|Operation mask]] can be used instead of new name. Filename can be replaced with [[file_mask|wildcard]] to select multiple files. | ||
| - | |||
| - | Alias: ''rename'' | ||
| - | |||
| - | XML log element: ''[[logging_xml#mv|mv]]'' | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | 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 | ||
| - | </code> | ||
| - | |||
| - | ===== open ===== | ||
| - | Establishes new connection. | ||
| - | |||
| - | open <stored_session> | ||
| - | open <session_url> | ||
| - | |||
| - | Establishes connection to given host. Use name of the [[session_configuration#stored|stored session]] (to open session, stored in folder, use path syntax “folder/session”) or [[session_url|session URL]]. | ||
| - | |||
| - | Switches: | ||
| - | ^ Switch ^ Description ^ | ||
| - | | ''-privatekey=<key>'' | [[public_key#private|Private key]] path | | ||
| - | | ''-timeout=<sec>'' | Server response timeout | | ||
| - | | ''-hostkey="<fingerprint>"'' | Specifies fingerprint of expected [[ssh#verifying_the_host_key|SSH host key]] (or several alternative fingerprints separated by semicolon). It makes WinSCP automatically [[scripting#hostkey|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 [[ftps#certificate|SSL/TLS sertificate]] (or several fingerprints separated by semicolon). It makes WinSCP automatically [[scripting#hostkey|accept certificate]] with the fingerprint. [[ftps|FTPS]] protocol only. | | ||
| - | | ''-passive=on%%|%%off'' | Enables [[ui_login_connection#connection|passive]] (''=on'') or active (''=off'') transfer mode ([[FTP]] protocol only). &beta_feature | | ||
| - | | ''-implicit'' | Implicit TLS/SSL ([[ftps|FTPS protocol]] only) | | ||
| - | | ''-explicitssl'' | Explicit SSL ([[ftps|FTPS protocol]] only) | | ||
| - | | ''-explicittls'' | Explicit TLS ([[ftps|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''. &beta_feature | | ||
| - | |||
| - | XML log element: ''[[logging_xml|session]]'' | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | 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 | ||
| - | </code> | ||
| - | |||
| - | ===== 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: ''[[scriptcommand_get|get]]'', ''[[scriptcommand_put|put]]'' | | ||
| - | | ''transfer'' | ''%%binary|ascii|automatic%%'' \\ [[transfer_mode|Transfer mode]]: binary, ascii (text), automatic (by extension). \\ Commands affected: ''[[scriptcommand_get|get]]'', ''[[scriptcommand_put|put]]'', ''[[scriptcommand_synchronize|synchronize]]'', ''[[scriptcommand_keepuptodate|keepuptodate]]'' | | ||
| - | | ''exclude'' \\ ''include'' | ''%%clear | <mask>[;<mask2>...]%%'' \\ Sets [[ui_transfer#other_options|exclusion or inclusion]] [[file_mask|masks]] (only one can be set at time). \\ Commands affected: ''[[scriptcommand_get|get]]'', ''[[scriptcommand_put|put]]'', ''[[scriptcommand_synchronize|synchronize]]'', ''[[scriptcommand_keepuptodate|keepuptodate]]'' | | ||
| - | | ''reconnecttime'' | ''%%off | <sec>%%'' \\ Sets time limit in seconds to try reconnecting broken sessions. \\ Commands affected: ''[[scriptcommand_get|get]]'', ''[[scriptcommand_put|put]]'', ''[[scriptcommand_synchronize|synchronize]]'', ''[[scriptcommand_keepuptodate|keepuptodate]]'' | | ||
| - | |||
| - | Aliases: ''ascii'' (for ''option transfer ascii''), ''binary'' (for ''option transfer binary'') | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | 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 | ||
| - | </code> | ||
| - | |||
| - | Note that resetting the same option overwrites a previous value, it does not append. | ||
| - | |||
| - | ===== put ===== | ||
| - | [[task_upload|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|operation mask]] to store file(s) under different name. Destination directory must end with slash. Filename can be replaced with Windows wildcard ((Windows wildcard supports ''*'' and ''?'' only. It does not support all the features of [[file_mask|file masks]].)) to select multiple files. To upload more files to current working directory use ''./'' as the last parameter. | ||
| - | |||
| - | Use [[scriptcommand_option|option]] command to set [[transfer_settings|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|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 [[scriptcommand_option|options]]: ''transfer'', ''confirm'', ''exclude'', ''include'', ''reconnecttime'' | ||
| - | |||
| - | XML log elements: ''[[logging_xml#upload|upload]]'', ''[[logging_xml#chmod|chmod]]'' (with ''-permissions''), ''[[logging_xml#touch|touch]]'' (with ''-preservetime'') | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | 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 | ||
| - | </code> | ||
| - | |||
| - | See also ''[[scriptcommand_synchronize|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 [[ui_login_environment#recycle_bin|remote recycle bin]] is configured, moves file to the bin instead of deleting it. Filename can be replaced with [[file_mask|wildcard]] to select multiple files. | ||
| - | |||
| - | XML log element: ''[[logging_xml#rm|rm]]'' | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | rm index.html | ||
| - | rm index.html about.html | ||
| - | rm *.html | ||
| - | </code> | ||
| - | |||
| - | ===== rmdir ===== | ||
| - | Removes one or more remote directories. | ||
| - | |||
| - | rmdir <directory> [ <directory2> ... ] | ||
| - | |||
| - | If [[ui_login_environment#recycle_bin|remote recycle bin]] is configured, moves directory to the bin instead of deleting it. | ||
| - | |||
| - | XML log element: ''[[logging_xml#rm|rm]]'' | ||
| - | |||
| - | Example: | ||
| - | <code winscp> | ||
| - | rmdir public_html | ||
| - | </code> | ||
| - | |||
| - | ===== session ===== | ||
| - | Manages opened sessions. | ||
| - | |||
| - | session [ <session> ] | ||
| - | |||
| - | Makes session specified by its number active. When session number is not specified, lists connected sessions. | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | session 1 | ||
| - | session | ||
| - | </code> | ||
| - | |||
| - | ===== synchronize ===== | ||
| - | [[task_synchronize_full|Synchronizes directories]]. | ||
| - | |||
| - | 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'' | [[task_synchronize_full#synchronization_mode|Mirror mode]] (synchronize also older files). Ignored for ''both''. | | ||
| - | | ''-criteria=<criteria>'' | [[ui_synchronize#comparison_criteria|Comparison criteria]]. Possible values are ''time'', ''size'', ''either'' (//Previous versions used value ''both''//&beta) 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 [[scriptcommand_option|options]]: ''transfer'', ''exclude'', ''include'', ''reconnecttime'' | ||
| - | |||
| - | XML log elements: ''[[logging_xml#download|download]]'' (with ''local'' or ''both''), ''[[logging_xml#upload|upload]]'' (with ''remote'' or ''both''), ''[[logging_xml#touch|touch]]'' (with ''remote'' or ''both''), ''[[logging_xml#chmod|chmod]]'' (with ''remote'' or ''both'' and ''-permissions''), ''[[logging_xml#rm|rm]]'' (with ''remote'' and ''-delete'') | ||
| - | |||
| - | Examples: | ||
| - | <code winscp> | ||
| - | synchronize remote -delete | ||
| - | synchronize both d:\www /home/martin/public_html | ||
| - | </code> | ||