Cli-Mate Documentation

What is CLI-Mate?

CLI-Mate is simply a windows application that can run many basic but powerful command line applications and interact with it from within the main application window. No need for a DOS box, simply run cmd.exe, 4dos, cygwin, python, PHP or many other command line interface based applications, or even run a SSH session to a remote server (dumb terminal output only).
Designed for my own personal use, as I use a number of CLI applications, DOS and Cygwin based, and need to connect to remote VPS systems, and I use a screen reader, which can be quite cumbersome and slow. So here is CLI-Mate, which allows for simple and easy navigation of the output, a separate input area which automatically traps your typed commands, even if half-way through reviewing some output, which allows for quick movement between previous commands, a full history of input actions and the response from the CLI, bookmarking, copying and pasting, finding text, simple macros and for the experienced Python programmer, complete control over the application during run-time.
So if you are an experienced computer user who needs a better IDLE for Python, who wants to use cygwin but finds the command line hard to access, or simply wants to use the dir command from time to time, CLI-Mate should work for you.
Please note that CLI-Mate is NOT a terminal program, and deals with applications that do simple "line-printer" style output only, so don't expect vt100 escape code handling and "screen review" options, just basic good old type some stuff, get back some text, no more, no less.

Installation

These installation instructions are quite terse, and if you do not understand them, then CLI-Mate is probably not the application for you. It is a tool for experienced command line users, or those experienced with the computer who are wanting to use the various command line options available.
  1. CLI-Mate is distributed as a single zip file and all relevant files needed to run the application are placed into a single directory, with no files needing to be placed in the windows or user directories.
  2. Unzip the package to a folder of your choice.
  3. Create a shortcut to CLI-Mate.exe on your desktop, add to your programs list, or create a short-cut key, entirely up to you. You may run the program from a differing working directory and a separate .ini file can be created in each working directory (see configuration section for more details).
  4. Either from explorer or your created shortcut, run CLI-Mate.exe
Please note that the zip has been created for windows 2000, XP or Vista and you will need to read the configuration section and alter the ini file for use on 9x or ME systems.

Basic Operation

Once CLI-Mate is up and running what you have in front of you is a single window with a menu, a read only rich edit text area and a single line edit control for inputting your commands. When the program first starts up it runs a specific command line "shell" such as cmd.exe or cygwin (I personally have it start up at a Python prompt). This can be changed to the command shell of your choice in the ini file, see the Configuration Section for details. The default when you first install is cmd.exe which is automatically started and run for you.
You are automatically placed into the input box where you can type commands for your specific shell, such as "dir" to get a directory listing.
Press the F9 key to move between the 2 windows (you can also use TAB to move from the output window to the input window but not back the other way, as the tab key is something you may want to send to the shell).
Once you have typed your command then press enter and your command and the response from cmd.exe (or what ever shell you are using) will be placed in the output window. You will automatically be placed there also with the cursor on the line of your command and the output following below.
Use the standard navigation controls of up, down, Page Up, Page Down, Home, End etc to move around.
If you are using a screen reader you can simply use the Say All command (JAWS key plus down arrow for example) to here the output.
Press the F9 key to move back to the input window or siply start typing and you will be placed back into the input box.
When in the input box, use the up and down arrow keys to access your previous commands.
When in the output window Ctrl-u moves you to the start of any previous command, Ctrl-i to the top of the current command / output section, and Ctrl-o to move you forward to newer sections.
F12 sets a bookmark and pressing F12 again when on the line where a bookmark is set turns it off. F4 jumps you forward through your bookmarks, while Shift-F4 moves you backwards.
Ctrl-F pops up a dialog to input some text to search for and F3 repeats the search forward, Shift-F3 searches back.

That's it! Enjoy, and see the Detailed instructions for Menu details etc.

Detailed Operation

Menus

File Menu

File -> Clear
Clears the output window and resets any bookmarks that have been sent. Useful to use when initialising or you have a long session.

File -> Local Echo Toggle
Choose this option to turn on / off local echoing of your input to the output window. For certain shells, your command is printed twice on the output window, so this option allows you to turn it off so that your command is seen only once.

File -> Single Char Mode.
This is semi-experimental, and is useful when a particular shell that wants each character one by one rather than a line of command string with a new line character appended. Next version will also have a "No auto New Line" option added to the menu. Note that if you are using this option then the only way to send a new line character is via the new line menu option on the Send menu.

File -> Initialise
The way that CLI-Mate works is by opening pipes to the underlying CLI Shell, and from time to time these pipes can get broken (please let me know the shell and program if you consistently have trouble with a given application.

File -> Exit
As you would expect, exits the application. Please note that there is no confirmation dialog to check that you are sure that you want to exit, so be careful. Let me know if you think it would be useful to have a confirmation dialog, and if there is enough agreement I will add one.

Send Menu

Send -> New Line
You can send just a new line character to the underlying shell application either by pressing enter within the input text box when the text box is empty, or by choosing this menu option. Useful in the odd occasion, especially when in single character input mode.

Send -> Ctrl-Z
This may or may not be in the release you have, as this option in many cases causes the pipe to the underlying application to break. Use at your own risk, and remember that this will more than likely break the pipe and cause you to have to initialise.

Send -> Ctrl-C
A commonly required character in Linux world.

Send -> Ctrl-D
A commonly required character in Linux world.

Pyklet Menu

This menu option is where you will find your own defined macros and commands, and is entirely up to you to populate. You do this by using a text editor and opening up Pyklet.ini and adding new sections to the file, and a couple of lines of detail for each new section, which becomes an item on the Pyklet menu.
When CLI-Mate is run, the application looks in the starting / working directory for pyklet.ini, and loads this if found. If one is not found then the program directory is searched and if pyklet.ini found then it will be loaded.
Multiple pyklet files can be created and when the program is run a specific one can be loaded by using the -ini command line switch. For example "CLI-Mate.exe -ini DOS_Pyklets.ini" will load the commands listed in DOS_Pyklets.ini.
The format of a pyklet file is as follows:
[Menu Name]
Desc= A Description of this command "
Code= The command(s) you want to perform "

Quotes are not required but please note the case of the keywords Desc and Code.

Help Menu

Help -> CLI-Mate Help
Loads this html document into your default browser.

Help -> About
Details the version and copyright details.

Keyboard Commands

There are a series of keyboard commands that differ dependant upon whether you are reviewing output or inputting text

Output Window

Any alphanumeric key
Pressing any alphahumeric key on its own will automatically jump you to the text input box and the character you pressed will be the first character in the input box. This allows you to quickly review and type without having to worry about moving to to the input area, very quick and easy.

F9 and TAB
Moves you to the input text box and selects the current contents. if you then begin typing you will overwrite whatever is in the input text box, so you will need to press right arrow to deselect and append text.

Ctrl-U, Ctrl-I, Ctrl-O
Used to move you around output based on sections of text being the output of a given typed command. For example let us presume you are using cmd.exe as your shell and you typed 3 separate commands "dir *.txt", "dir *.exe", and finally "type readme.txt". Each one of these commands would have had some output associated with it and you may want to move between each section. Pressing Ctrl-U will move you to the previous command and its output, say from the type command to the dir *.exe listing. Pressing Ctrl-U again would move you to the top of the dir *.txt output.
Ctrl-I takes you to the top of the current output section and Ctrl-O moves you forward to the next output section.
Attempting to move forward or back beyond the available output sections is not allowed and you will hear a beep and your reading cursor will not move.
It is worth playing with these movement keys as they can be very useful in some situations, like the linux man pages for example.

Standard navigation keys
Standard text box navigation keys can be used to move around, arrows, home, end, Page Up, Page Down etc and also with Ctrl and or Shift key.

Ctrl-C
Copies selected text to the clipboard.

F12
Sets / Unsets a bookmark at the current cursor position

F4 and Shift-F4
Jumps to next / previous bookmark. Will wrap to top or bottom and if this does occur you will hear an exclamation tone to let you know.

Ctrl-F
Pops up a dialog into which you can type some text to Search for.

F3 and Shift-F3
Searches forward or back through output window looking for the text you input to find. If no text to search for has been input, the find dialog will pop up and you will need to input some. The search will wrap around the top and bottome and if this occurs you will get an audible exclamation sound.

Text Input Box

When you first start up the application you are placed into this box so that you can type your first command. The following list are the extra key commands you can use besides the standard alphanumeric keys and edit keys such as right and left arrow. Pressing the ENTER key will send whatever is in the text box to the underlying application and you will be placed in the text output area at the top of the response from the application.

F9
Moves you to the output window to allow you to review the output text.

Up and Down Arrow
You can reuse a command that you typed in previously by simply pressing on the up arrow key. This moves you backwards through the last 20 commands input. Pressing the down arrow moves you the other way through the list. As you cycle, forward or back, the command is placed into the input box and is selected, so if you want to edit it you will need to move the cursor before typing any alphanumeric keys. You can delete the history.lst file if you do not want others to see passwords and the like you have typed at some point in the past. A new empty history.lst file will be created next time the application is run.

Ctrl Z
This is a simple undo and can be used as many other places in windows when using a standard edit box.

Configuration

This application is very simple and there is not a lot of configuration, however it can be handy to have a couple of different .ini files created and placed with a shortcut in differing folders so that different command line applications can be run quickly and simply.
Configuration needs to be done manually by using a text editor and editing / copying the .ini file found in the application directory. If the program is run in a differing working directory and an .ini file is found in that directory, the application will be run with those configuration settings.

The .ini file

At time of writing there are only 3 specific configuration settings, if more are added at a later time these will be explained in the ini file itself. They are all self explanatory and the most important one is the Shell / cmd one which tells the program which underlying command line application to run and trap commands to and from. The most common options for "cmd=" are as follows: Nearly any command line application can be run, but there are some applications that can behave strangely. Please note that command.com does not write to the screen in a standard manner and so cannot be used, instead try 4DOS, which is now freely available. Cygwin works fine, though I am yet to have it work 100% correctly as I have not worked out how to set the terminal type to "dumb" and so do have issues with some cygwin commands. I have found a workaround and that is to run sshd as a service and then simply ssh back to myself and this works perfectly.
If you come across particular applications that don't appear to work then please let me know and the same if you find a command line application that is really useful, I am always looking to expand the programs I use.

Advanced Options and run-time control

This is for advanced programmers only and becaused of this I will provide only a brief overview here. If you are not comfortable with callbacks and python, DO NOT PLAY!
Basically you can add new functions into user_commands.py and then "call" that function within the program by typing $$.
You can access the menus / output / input areas from the obj param and if you do so, you may cause side effects, so this is very much at your own risk. If you make useful changes please pass back to me as I may incorporate at some point.

FAQ

Can I run any DOS or Linux program that I want to?

A. Most definately not. Many applications that used to work under DOS were not command line applications, they were simply started from the command line. An example of this was WordPerfect the word processor or Lotus 1-2-3. These are fully fledged console applications that use the entire screen and control their own input and output and as such cannot be used from inside Cli-Mate.
If you accidently start one of these types of programs then you may have to quit or re-initialize Cli-Mate before continuing.

A certain program works under CMD.exe but not under Cli-Mate, why?

A. Cli-Mate is a simple interface that traps a certain type of input and output only, known as stdout and stdin. Not all applications use this preferred mechanism of interacting with computer users. It is most likely that if a particular application (command.com for example) will not work it is for this reason, and unfortunately there is no easy solution to this.

How do I SSH to a remote computer?

A. A separate program has been written to allow you to do this without having to have any other external dependancies. If you want to do it yourself then check out the python library called Paramiko which can be used to create your own connections and also for doing SFTP. However you can simply run up a cmd.exe within Cli-Mate, go to the directory where Cli-Mate is installed and from the Clissh sub-directory run Clissh.exe. This provides a bare bones and simple way to connect to remote machines using a dumb terminal.

Sometimes I see ***EIF *** on the screen after issuing a command what's this about?

A. This can happen when you have run an external command or program that is finished and the pipe has been closed. Simply go to the input box by pressing F9, clear everything and press enter (send a Newline character), this should pop you back to your underlying shell.

Troubleshooting and Bugs

There are no bugs known at the time of this release which causes the program to crash. No doubt there are bugs and issues like this, so if you come across any please report these so they can be fixed in any future releases. Send an email to darryl@povidi.com with the subject line Cli-Mate bug report and this will then be attended to.

Legal Stuff

In this day and age, this has to be noted.
1. By using this application you agree to accept all following basic conditions.
2. This software is distributed without warrenty and you use at your own risk. The author takes no responsibility for any damage or loss occurring from the use of it. All efforts have been made to make the software stable and safe to use but without any acceptance of responsibility.
4. This software should not be disassembled and all intellectual property and copyright remains the property of Povidi NZ Ltd. H