Command Line Interface (CLI)
1. Console Window
Wiimms SZS Tools is a set of command line tools.
There is no graphical user interface
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
and many more.
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
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!
The tools use the GNU C Library
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
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
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.
Read your shell documentation for details!