Command Line Interface (CLI)

1. Console Window

Wiimms ISO 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 WIT 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.

If you want access to a USB drive (standard for tool wwt) you need special rights; use one of the following methods:

Work in a root shell.
Use su or sudo to access the USB drive.
Modify the access rights of the USB drive permanently.

1.1.1 Access a WBFS drive without root privileges

It's possible to work with already formatted WBFS partitions without root privileges.

Create the file /usr/local/bin/wbfs-chmod:

   #!/bin/bash
   /usr/local/bin/wwt find | while read dev
   do
      echo chmod 666 "$dev"
      chmod 666 "$dev"
   done

Do: chmod a+x /usr/local/bin/wbfs-chmod

Add the following line to /etc/sudoers:

   ALL ALL=NOPASSWD: /usr/local/bin/wbfs-chmod

Each user can now call sudo wbfs-chmod to change the mode of every WBFS partition to public read and write access. The command must be entered every time when a WBFS drive is plugged in.

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.

If you want access to a USB drive (standard for tool wwt) you need special rights; use one of the following methods:

Open a administration windows (don't ask me how to do this).
Modify the access rights of the USB drive permanently. (I don't know if this is really possible)

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 stating 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. This 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 to the shell.

Read your shell documentation for details!

3. Options

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

The WIT 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: --disc-id=id --boot-id=id can be written without minus signs as --discid=id --bootid=id.

3.1 Multiple usage of options

If an option is used multiple times the meaning depends of the kind of option. The WIT 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 --files 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 --wdf, --iso, --ciso, --gcz, --wia and --wbfs is used to force the output file 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. The tools wit and wwt 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 './', because './-myfile' is the same file.

5. Command Line Expansion

Global parameters and some option parameters allow to read it 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. If you append '| less' or '| more', the output is redirected to a pager that allows reading of long outputs.