--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Simtool-command-shell	Sat Feb 20 23:55:25 2021 +0000
@@ -0,0 +1,124 @@
+Our fc-simtool and fc-uicc-tool operate as interactive shells.  When you run
+either program, it selects the "card reader" device it will use and connects to
+the card via pcsc-lite facilities, and then it gives you an interactive command
+shell.  The communication session with the card (including vital volatile state
+like PIN authentication and currently selected directory and EF) remains
+unbroken until you exit the shell, at which point our tools tell pcsc-lite to
+power down the card.
+
+The actual useful commands available in fc-simtool and fc-uicc-tool are
+described in other documents; this document describes program invokation and
+the command shell itself.
+
+Program invokation
+==================
+
+Both tools share the same command line structure:
+
+fc-simtool [-p num] [batch-command]
+fc-uicc-tool [-p num] [batch-command]
+
+If you run either tool without any options or arguments, it will select the
+first reader supported by pcsc-lite (reader number 0, same as if -p0 was
+specified), and if the card connection is successful, it will enter the
+interactive command shell.  Use the -p num option to select a different reader
+number; to tell which reader number is which, use fc-pcsc-list to list all
+available readers.
+
+Aside from the -p num option, any arguments given on the command line suppress
+the default interactive shell and select the tool's batch mode instead - the
+arguments specify the command to be executed.  For example, the following
+invokation will read and display the inserted card's ICCID, and immediately
+exit:
+
+fc-simtool iccid
+
+This batch mode is particularly useful with the exec command described further
+in this document.
+
+Command shell basic features
+============================
+
+The interactive command shell prompt is "simtool> " in fc-simtool and "uicc> "
+in fc-uicc-tool.  In this interactive command shell mode commands are entered
+naturally, with white space separating the command keyword and any arguments.
+Arguments containing spaces need to be enclosed in double-quotes as in
+"quoted string"; our tools have two main instances where such complex arguments
+are used:
+
+* Many of our commands, particularly low-level ones, take hexadecimal byte
+  strings as arguments.  In such hex byte strings each byte must be given as
+  exactly two hex digits (no 0x and no single-digit bytes for small values),
+  but spaces between bytes for human readability are optional.  If these
+  optional spaces are included, the whole argument needs to be included in
+  double-quotes.
+
+* Some of our commands take arguments that represent GSM 03.38 text strings,
+  using our ASCII representation format for such strings that is defined in the
+  SIM-data-formats document in the freecalypso-docs repository.  If these
+  arguments contain spaces, they need to be enclosed in double-quotes, and any
+  embedded '"' characters need to be entered as \".
+
+Output redirection
+==================
+
+Most of our information retrieval and dumping commands support output
+redirection at the tool-internal command shell level.  For example, the
+following command will list the SIM Service Table (SST) on the terminal and
+redisplay the "simtool> " prompt:
+
+simtool> sst
+
+The following form of the same command will write the output to the named file
+and not send anything to the terminal:
+
+simtool> sst > sst-list-file
+
+If you try the '>' output redirection construct on a command that does not
+support it, you will get an error message.
+
+Working with the local host file system
+=======================================
+
+Because our tools provide a lot of commands for saving SIM data into host files
+(the above output redirection mechanism and some binary file writes) as well as
+reading data and command scripts from host files, having a sensible interaction
+with the local host file system is important.  Users should have a convenient
+way to see what directory they are in, change their current directory, and
+invoke other local host commands like mkdir from inside their fc-simtool session
+- hence the following features are provided:
+
+* Any command beginning with '!' is passed to the system shell /bin/sh - the
+  primary use of this feature is to be able to run !pwd to see what directory
+  you are in, and more rarely do other things like !mkdir mysimdata.
+
+* The built-in cd command changes the current directory of the running
+  fc-simtool process - because of the way UNIX works, cd is one command that
+  cannot be usefully executed via the '!' shell invokation mechanism.
+
+Command script facility
+=======================
+
+Both fc-simtool and fc-uicc-tool implement an exec command:
+
+exec script-file
+
+This command opens the named file, reads it line by line, and executes each
+read line as a command.  Whitespace-only lines are skipped, and any lines
+beginning with '#' are treated as comments.  exec scripts can be nested.  If
+the execution of any command encounters an error, all nested scripts are
+stopped: we implement the "stop on first error" policy.
+
+If the given script file name contains any slashes, it is used as-is.  If there
+are no slashes in the requested script file name, the file is sought first in
+the script installation directory /opt/freecalypso/sim-scripts, and if it is
+not found there, then in the current directory.
+
+Data file sourcing
+==================
+
+All fc-simtool and fc-uicc-tool commands that read from ASCII-based data files
+named as arguments implement the same search logic as the exec command.  This
+design allows complex SIM programming scripts to be installed in
+/opt/freecalypso/sim-scripts along with their data files, ready to be invoked
+as needed.