Command Line Interface (CLI)

1. Console Window

Wiimms SZS Tools is a set of command line tools. There is no graphical user interface (GUI). The user have to type the commands including options and parameters into a text console or as script (batch file). The results are printed to the text console, if not redirected.

The advantage of a command line interface (CLI) is that frequently needed commands can be stored into shell scripts (Windows calls them batch files). The SZS tools terminate with different exit codes that can be anlayzed in shell scripts.

If calling a tool from the desktop, a text window opens and closes immediately, because the tool prints only a help message and terminates. Best is to open a console terminal first and entering the commands in this open terminal window. Alternatively a script (batch file) can be written and startet by a click.

1.1 Linux and other Unix derivates

With Linux and other Unix derivates you have the choice between many shell programs like sh, bash, csh, tcsh, ksh and many more.

1.2 Windows

Windows knows the command cmd. It is sometime called DOS Window, but it has nothing to do with DOS, because it opens a fully Windows compatible text console window.

There are several way to open a command window:

Execute the program cmd.
With installed powertoys right click and select "Command line here".
Create a batch file with the single line »cmd« and click it.
Other ways, that I don't know.

I recommend the Total Commander for general command line usage on Windows systems. It is a very good file browser and manager with many features and can replace the the Windows Browser completely. At bottom it accepts command lines, that are executed in the current directory. By typing simply cmd, a command window opens with the correct working directory.

2. The command line

The command line is interpreted as a sequence of blank-separated words. BLANK means in general SPACES and TABS, this depends on the used shell.

Each word is interpreted as option (if starting with a minus sign '-') or as parameter else. If a parameter contains one or more blanks, enclose it with single or double quotes: 'one word' or "one word". Windows supports only the double quotes. Quotes removes also the special meaning of certain characters or words to the shell.

Certain characters with special meaning are also different in the different shells. Characters like semicolon (';'), exclamation point ('!'), dollar sign ('$'), percent sign ('%'), number sign ('#'), less sign ('<'), greater sign ('>') and the quotes have very often a special meaning for the shell.

Read your shell documentation for details!

3. Options

The tools use the GNU C Library function getopt_long() to analyze the command line and find out the options.

The SZS tools support short and long options. For example the tools know the options --verbose and --test and the short versions -v and -t. Some options need a parameter like --source path (short version: -s path). As you see, short options are prefixed with a single minus sign ('-') and long options are prefixed with a double minus sign ('--').

It is normal that every option and every parameter (needed by an option or global) is written as exact one word, but short options can be combined in one word:
--verbose --test is the same as -v -t and also the same as -vt.

If a short option takes a parameter it must be the last option of the option list:
-vs path same as -vspath, but -sv path is different.

Long options with parameters can be written in two forms:
--source path is same as --source=path.

For all options, that contains one or more minus signs in their names, alternative names without minus signs are available. This concept is also used for keywords.
Example: --load-kcl=file --kcl=DROP-UNUSED can be written without minus signs as --loadkcl=file --kcl=DROPUNUSED.

3.1 Multiple usage of options

If an option is used multiple times the meaning depends of the kind of option. The SZS tools support three kinds of options:

Accumulative options are always options with parameters. All parameters are collected and stored into an internal list. --source and --recurse are examples for accumulative options.
Counting options are always options without parameters. The number of appearances is counted to compute a level. --verbose and --logging are examples for counting options.
All other options are standard options. For standard options only the appearance is registrated, not the number of appearances. If a standard options takes a parameter only the parameter of last appearance is stored. --overwrite and --dest are examples for standard options.

Some options cancel the effect of other option. For example only the last appearance of --u8, --szs, --brres and --breft is used to force the output archive format.

4. Global Parameters

All words of the command line, that are not options and not parameters for options, are global parameters.

The order of global parameters is importand. They are analyzed after the options. All tools use the first global parameter as command. All other parameters are used as additional info.

If you want to insert a file, that begins with a minus sign like '-myfile', prefix it with './' (e.g. './-myfile'); otherwise it is detected as option.

5. Command Line Expansion

Global parameters and some option parameters allow to read its parameters from files. Just write '@file' instead of 'parameter'.

The Cygwin (Windows) version interpretes '@file' by itself. If using with an option you must prevent this Cygwin interpretation by quoting the option parameter.

6. Redirect output to a file

If you want to store the output of a command in a file, just append '>path' at the end of the command line. The standard output, but not the error output, is then redirected to the file with the given path.

You can also pipe the output to other tools. Append '| other_command' at the end of the command line. If you append '| tee path', then the output is written to the console and to the file with the entered path (that is the job of tool tee). If you append '| less' or '| more', the output is redirected to a pager that allows reading of long outputs.