Note: This Guide applies to TouchTerm 1.1.

Click here for the Guide for the current version of TouchTerm.

Connection screen

Enter the server, port, username, and password for the new connection. TouchTerm will remember the last-used values. Note that passwords are only stored if you choose "Save Passwords" in Settings.

Tap "Connect" go being a new session.

Terminal Screen

After a successful connection, a new terminal window will come up displaying your shell prompt.

Note that this is a fixed-width window (80 columns), but is no longer restricted to the edges of the device screen. Scroll left and right to reveal different screen areas. For better readability, rotate the device into landscape mode.

The standard pinch zoom gestures are now supported in the terminal window. The zoom is limited by the font size, however; if you want to fit more text on your screen, go to the Settings screen (upper-right button) and reduce the font size.

Whenever you are typing, TouchTerm will auto-scroll the window's contents so that the cursor is visible. Of course, you can still adjust the scrolling manually while the keyboard is up. TouchTerm will not auto-scroll when the keyboard is not visible.

Settings Screen

From the Settings tab, or using the Settings button in the upper-right hand corner of the Terminal Screen, TouchTerm allows you to control several attributes of the terminal display and operation. The text, background, and cursor colors can all be customized.

Use the Font Size slider to control the default (non-zoomed) size of the output text in the terminal window. Note that this effectively sets the minimum size of the text; from the terminal window, you can use the standard pinch gestures to zoom in and magnify text.

The Save Passwords switch controls whether or not TouchTerm remembers the password that you entered for the last connection.

The Auto-Return Mode and Immediate Mode switches control how you interact with server. These will be described in more detail below.

Entering Commands: Auto-Return Mode

TouchTerm has several ways to communicate with the server. The default is "Auto-Return Mode". To enter a command, first tap on the command box that appears directly below the button bar. (Note that you can tap once anywhere on the output window to show and hide the command box.)

The keyboard will raise, allowing you to enter a command into the command box. Note that as you type, nothing is sent to the server. When you tap "return", the entire contents of the command box are sent to the server, including a newline character (i.e., the equivalent of hitting the "return" key on a standard keyboard).

This mode is most useful when using the command-line directly. You can enter each command in full, and correct mistakes locally, before sending the command to the server. Also, Auto-Return Mode enables the use of the command history, which allows you to re-issue and/or correct recently issued commands. (See below for more details on using the command history.)

If you just want to send a single newline character without any text, you can just tap the return key when the command box is empty.

If you want to hide the keyboard in order to see more of the output display, simply tap once anywhere on the terminal output window. Once the keyboard is hidden, you can again tap once on the terminal window to hide or show the command box.

Entering Commands: Batch Mode

To enable "Batch Mode", tap the Settings button (rightmost on the toolbar) and set both Auto-Return Mode and Immediate Mode to "OFF". Batch Mode is similar to Auto-Return Mode: you type characters into the command box, and when you are finished you tap "return" to send those characters to the server. However, in Batch Mode, a newline character is NOT automatically added: just the characters that you typed are sent.

This is most often useful when interacting with programs that do not expect a return key, or for using tab completion and other shell features. For example: to use tab completion in Batch Mode, you would enter a partial command into the command box, tap "return", and then tap the Tab button.

In Batch Mode, if you need to enter a single newline character, you can do so by tapping "return" when the command box is empty.

Note that because partial commands will often be entered, the command history is not updated in Batch Mode.

Entering Commands: Immediate Mode

In Immediate ("Raw") Mode, TouchTerm operates in the same way as standard terminal programs: every keypress that you issue is immediately sent to the server. The command box is never visible in Immediate Mode: in order to send keystrokes, simply tap once on the terminal output window, which will bring up the keyboard display. As you type, you will see that keypresses are sent directly to the server and the output is updated appropriately.

Immediate Mode is most useful when using interactive programs, such as emacs or vi. Some users may even prefer to use Immediate Mode for all tasks.

Note that since Immediate Mode passes all keystrokes to the server, the command history will not be updated.

Using Command Keys

TouchTerm supports the most commonly used special characters, using the buttons in the toolbar. Note that the "Tab" and "Esc" buttons always send the keystrokes immediately to the server, even in Batch Mode or Auto-Return Mode.

Tapping the "Ctrl" button initiates a Control-key command. This will raise the keyboard (if it's not visible already), and the next character pressed will be submitted as a control sequence. For example, to send a Ctrl-C (break), tap the "Ctrl" button and then tap the "C" key.

If you tap the Ctrl button and then decide you don't want to send a control character, you can tap the Ctrl button again to cancel.

Finally, TouchTerm also supports the backquote character "`", which is not available on the iPhone keyboard. You can enter a backquote by tapping the "dot" key: this is found on US English keyboards by tapping "?.123", then "#+=", then it's in the second row at the right side of the keyboard. Note that the dot character will still appear in the command box if using Batch Mode or Auto-Return Mode, but the backquote character will be transmitted to the server.

NOTE: there is a known bug with using the backquote character in Immediate Mode, which causes TouchTerm (v1.1) to crash. It will be fixed in the next update.

Clearing the Display

The "Clear" button in the upper-left can be used for clearing the terminal window output buffer. TouchTerm will not clear any terminal output unless explicitly requested using this key. This way, you can scroll back up through large amounts of text, and use clear to prune it when you no longer need it.

Working with History

When using Auto-Return Mode, most commands (anything that's at least 2 characters) are stored in the command history. To access the command history, tap the disclosure button to the right of the command box. This will bring up the History screen. Commands in the history are ordered with the most recent command at the top. To select a history item, simply tap the corresponding row: that command will then be entered into the command box, and you will be returned to the Terminal screen. Note that TouchTerm then allows you to edit the command before sending it off to the server; this is useful for correcting typos.

The command history can be used in either Auto-Return Mode or Batch Mode. However, note that in Batch Mode, new entries are not added to the history list. Command history is not available in Immediate Mode.

One thing to note is that in Auto-Return Mode, all commands sent to the server are added to the command history -- even if they are not sent to the command-line shell. One place this might be problematic is for passwords: if you enter a password while in Auto-Return Mode, it will be saved in your command history. This is probably not desired; one way to work around this for now is to set TouchTerm to Immediate Mode whenever you have to enter a password. (We're planning to add more sophisticated password management to TouchTerm and TT Pro!)