# The &konsole; Handbook

&Jonathan.Singer; &Jonathan.Singer.mail;
&Kurt.Hindenburg; &Kurt.Hindenburg.mail;
&Robert.Knight; &Robert.Knight.mail;
&Kurt.Hindenburg; &Kurt.Hindenburg.mail;
&Waldo.Bastian; &Waldo.Bastian.mail;
&Mike.McBride; &Mike.McBride.mail;
2000
2001
2002
&Jonathan.Singer;
2005
2008
2009
&Kurt.Hindenburg;
&FDLNotice;
2009-04-12
2.3.0

&konsole; is &kde;'s terminal emulator.

KDE
konsole
kdebase
command
line
terminal
cli

## Introduction

### What is a terminal?

&konsole; is an X terminal emulator, often referred to as a terminal or a shell. It emulates a command line interface in a text only window.

Explaining the use of the &UNIX; CLI is beyond the scope of this document. A search of the web for these terms will produce more information.

### Scrollback

&konsole; uses the notion of scrollback to allow user's to view previously displayed output. By default, scrollback is on and set to save 1000 lines of output in addition to what is currently displayed on the screen. As lines of text scroll off the top of the screen, they can be reviewed by moving the scroll bar upwards, scrolling with a mouse wheel or through the use of the &Shift;Page Up (to move back a page), &Shift;Page Down (to move forward a page), &Shift;Up Arrow (to move up a line) and &Shift;Down Arrow (to move down a line) keys.

When the scrolllock is on, ordinary input and output from the shell is suspended, and you can scroll through the history with Page Up, Page Down, Up Arrow and Down Arrow.

&konsole; provides a number of actions located in the Scrollback menu.

### Profiles

Profiles allow the user to quickly and easily automate the running of common commands. Examples could include:

- ssh into another machine

- starting an irc session

- use tail to watch a file

Procedure to create a new profile:

1. Click on the menu entry Settings Manage Profiles...

2. Click on the button New Profile....

3. Fill in the first entry with a name. This is the name that will show in the menu, and will be the default label instead of Shell when you start a session of this type.

4. Enter a command just as you normally would if you opened a new shell and were going to issue that command. For our first example above, you might type ``ssh` administration`.

5. On the other tabs of the dialog, configure this session's appearance. You can configure a different font, colour scheme, $`TERM` type and many other settings for each session.

6. Press the OK button. The new session is now available in the Manage Profiles... dialog.

After creating profiles, they are listed by their name in the File menu underneath the default Shell item.

### Mouse Buttons

This section details the use of the mouse buttons for the common right handed mouse button order. For the left handed mouse button order, swap left and right in the text below.

Left

  All &LMB; clicks will be sent to a mouse-aware application running in &konsole;. If an application will react on mouse clicks, &konsole; indicates this by showing an arrow cursor. If not, an I-beam (bar) cursor is shown.

  Holding the &LMB; down and dragging the mouse over the screen with a mouse-unaware application running will mark a region of the text. While dragging, the marked text is displayed reversed for visual feedback. Select Copy from the Edit menu to copy the marked text to the clipboard for further use within &konsole; or another application. The selected text can also be dragged and dropped into compatible applications. Click on the selected text and drag it to the desired location. Depending on your &kde; settings, you may need to hold the &Ctrl; key while dragging.

  Normally, new-line characters are inserted at the end of each line selected. This is best for cut and paste of source code, or the output of a particular command. For ordinary text, the line breaks are often not important. One might prefer, however, for the text to be a stream of characters that will be automatically re-formatted when pasted into another application. To select in text-stream mode, hold down the &Ctrl; key while selecting normally.

  Pressing the &Ctrl; and &Alt; keys along with the &LMB; will select a column of text.

  Double-click with the &LMB; to select a word; triple-click to select an entire line.

  If the upper or lower edge of the text area is touched while marking, &konsole; scrolls up or down, eventually exposing text within the history buffer. The scrolling stops when the mouse stops moving.

  After the mouse is released, &konsole; attempts to keep the text in the clipboard visible by holding the marked area reversed. The marked area reverts back to normal as soon as the contents of the clipboard change, the text within the marked area is altered or the &LMB; is clicked.

  To mark text on a mouse-aware application (Midnight Commander, for example) the &Shift; key has to be pressed when clicking.

Middle

  Pressing the &MMB; pastes text currently in the clipboard. Holding down the &Ctrl; key as you press the &MMB; pastes the text and sends it to &konsole;.

  If you have a mouse with only two buttons, pressing both the &LMB; and &RMB; together emulates the &MMB; of a three button mouse.

  If you have a wheel as the middle button, rolling it in a mouse unaware program will move &konsole;'s scrollbar.

Right

  These items appear in the menu when the &RMB; is pressed:

  Copy, Paste, Clear Scrollback & Reset, Open Browser Here, Change Profile, Edit Current Profile..., Show MenuBar, Character Encoding and Close Tab

  In a mouse aware application, press the &Shift; key along with the &RMB; to get the popup menu.

## Command Reference

### The Menubar

The menubar is at the top of the &konsole; window. If the menubar is hidden, Show Menu Bar can be reached by right clicking in the window (as long as no full screen application is running in that window such as vi, minicom, etc.). The default shortcut is listed after each menu item.

#### File Menu

&Ctrl;&Shift;N File New Tab

  Opens a new tab with the default profile

&Ctrl;&Shift;M File New Window

  Opens a new separate &konsole; window with the default profile

File Shell

  Opens a new tab with the Shell profile

  &konsole; ships with the Shell profile as the default. Any new profiles added by the user will have its own menu item below File Shell.

File Open Browser Here

  Opens &kde;'s file manager at the current directory. By default, that is &dolphin;.

&Ctrl;&Shift;W File Close Tab

  Closes the current tab

&Ctrl;&Shift;Q File Quit

  Quits &konsole;

  &konsole; will display a window if there is more than one tab open. This window can be disabled by clicking on the Do not ask again checkbox.

#### Edit Menu

&Ctrl;&Shift;C Edit Copy

  Copies the selected text to the clipboard

&Ctrl;&Shift;V Edit Paste

  Pastes text from the clipboard at the cursor location

&Ctrl;&Alt;S Edit Rename Tab...

  Opens a dialog box allowing you to change the name of the current tab (more info)

Edit Copy Input To...

  Allows input from the current session to be sent simultaneously to other sessions (more info)

Edit Clear Display

  Clears all text from the tab

  All the text cleared will be stored in the Scrollback.

Edit Clear & Reset

  Clears all text from the tab and reset the session

  All the text cleared will be stored in the Scrollback.

#### View Menu

&Ctrl;&Shift;L View Split View Split View Left/Right

  Splits all the tabs into left and right views

  Any output on one view is duplicated in the other view.

&Ctrl;&Shift;T View Split View Split View Top/Bottom

  Splits all the tabs into top and bottom views

  Any output on one view is duplicated in the other view.

&Ctrl;&Shift;S View Split View Close Active

  Closes the current view

&Ctrl;&Shift;O View Split View Close Others

  Closes the non-current view

&Ctrl;&Shift;] View Split View Expand View

  Makes the current view larger

&Ctrl;&Shift;[ View Split View Shrink View

  Makes the current view smaller

&Ctrl;&Shift;H View Detach View

  Opens the current tab in a separate window

  Quiting the previous &konsole; window will not affect the newly created window.

View Show Menu Bar

  Toggles the menubar being visible

&Ctrl;&Shift;F11 View Full Screen Mode

  Toggles &konsole; filling the entire screen

&Ctrl;&Shift;I View Monitor for Silence

  Toggles the monitoring of the current tab for lack of activity

  By default, after 10 seconds of inactivity, an info icon will appear on the session's tab. The type of alerts can be changed through Settings Configure Notifications Silence in monitored session.

&Ctrl;&Shift;A View Monitor for Activity

  Toggles the monitoring of the current tab for activity

  Upon any activity, an info icon will appear on the session's tab. The type of alerts can be changed through Settings Configure Notifications Activity in monitored session.

View Set Character Encoding

  Sets the character encoding

&Ctrl;+ View Increase Text Size

  Increases the text font size

&Ctrl;- View Decrease Text Size

  Decreases the text font size

#### Scrollback Menu

&Ctrl;&Shift;F Scrollback Search Output...

  Opens a search bar at the bottom of &konsole;'s window

  This allows for case sensitive, forward or backwards, and regular expressions searches.

F3 Scrollback Find Next

  Moves to the next search instance

&Shift;F3 Scrollback Find Previous

  Moves to the previous search instance

Scrollback Save Output...

  Saves the current scrollback as a text file

Scrollback Scrollback Options...

  Opens a dialog to configure number of lines to save (more info)

Scrollback Clear Scrollback

  Clears all text saved in current tab

&Ctrl;&Shift;X Scrollback Clear Scrollback & Reset

  Clears all text saved in current tab and resets the terminal

#### Bookmarks Menu

&Ctrl;B Bookmarks Add Bookmark

  Adds the current location

Bookmarks Bookmark Tabs as Folder...

  Adds all tabs to a bookmark folder

  A dialog will open for the bookmark folder name.

Bookmarks New Bookmark Folder...

  Adds a new folder to the bookmark list

  A dialog will open for the bookmark folder name.

Bookmarks Edit Bookmarks

  Opens the bookmark editor

  You can use the bookmark editor to manually add URLs like ssh://user@host:port to open remote connections.

#### Settings Menu

Settings Change Profile

  Changes the profile for the current tab

Settings Edit Current Profile...

  Opens the profile editor for the current tab

Settings Manage Profiles...

  Opens a editor for managing profiles

Settings Configure Shortcuts...

  Opens the keyboard shortcut editor

Settings Configure Notifications...

  Opens the notifications editor

#### Help Menu

&help.menu.documentation;

### Rename Tab Dialog

The name of the current tab can be changed from this dialog. The dialog can be displayed via the menu, the shortcut &Ctrl;&Alt;S or by double-clicking on the tab in the tab bar. These changes can be made permanent by editing the current profile.

&konsole; will subsitute these tokens:

- %n : program name

- %d : current directory (short)

- %D : current directory (long)

- %w : window title set by shell

- %# : session number

- %u : user name

Examples:

- `%d : %n` with /usr/src as current directory and running bash will display usr/s : bash

- `%D : %n` with /usr/src as current directory and running top will display /usr/src : top

- `%w (%#)` with ~ as current directory and running vim in the first tab will display [No Name] (~) - VIM(1)

### Copy Input Dialog

The text entered in one tab can simultaneously be sent to other tabs. This dialog allows you to select which tabs will get that input. The current tab will be greyed out.

### Scrollback Options Dialog

The scrollback option for the history size can be changed in this dialog. There is also a check box to save these settings to the current profile.

## Command-line Options

When &konsole; is started from the command line, various options can be specified to modify its behavior.

`--help`

  List the various options.

`--profile` `file`

  Start &konsole; using a saved set of sessions.

`--list-profiles`

  List all of the available profiles.

`--background-mode`

  Start &konsole; in the background and bring to the front when the F12 key is pressed.

`--new-tab`

  Create a new tab in an existing window rather than creating a new window.

`--workdir` `dir`

  Open with `dir` as the working (starting) directory.

`--notransparency`

  Disable transparent backgrounds, even if the system supports them.

`--force-transparency`

  Try to enable transparency, even if the system does not appear to support it.

`--hold, --noclose`

  Do not close the initial session automatically when it ends.

`-p` `property=value`

  Change the value of a profile property.

`-e` `command`

  Execute `command` instead of the normal shell.

  Any arguments after `command` will be passed to `command`, not &konsole;.

&konsole; also accepts generic &Qt; and &kde; options:

`--help-qt`

  List &Qt;-specific options

The following &Qt; options have no effect on &konsole;:

`--fn`, `--font` `fontname`

  Defines the application font

`--bg`, `--background` `color`

  Sets the default background color

`--fg`, `--foreground` `color`

  Sets the default foreground color

`--btn`, `--button` `color`

  Sets the default button color

`--help-kde`

  List &kde;-specific options

`--help-all`

  List all options

`--author`

  Show the authors' names

`-v,--version`

  Show the version number

`--license`

  Show license information

## Scripting &konsole;

For &kde; 4, the old &DCOP; has been replaced with &DBus;. &konsole; does support numerous methods that can be used with &DBus;.

There are two ways to use the &DBus; interface: &Qt;'s &GUI; qdbusviewer and the command line qdbus.

Examples:

- &percnt; `qdbus` will display all services available.

- &percnt; `qdbus` `org.kde.konsole-`pidof -s konsole`` will display the &DBus; interface for &konsole;.

- &percnt; `qdbus` `org.kde.konsole-`pidof -s konsole` /Konsole` will display methods for controlling the main &konsole; window.

- &percnt; `qdbus` `org.kde.konsole-`pidof -s konsole` /Session/1` will display methods for session 1.

In the above examples, ``pidof -s konsole`` will work if you have only one &konsole; window running. If you have more than one &konsole; running, you'll have to replace the above text with that pid of the &konsole; you want to control.

For more information, please visit &DBus; tutorial.

## Credits and Copyright

&konsole; is currently maintained by &Robert.Knight; &Robert.Knight.mail;

Previous &konsole; maintainers include: &Kurt.Hindenburg; &Kurt.Hindenburg.mail; and &Waldo.Bastian; &Waldo.Bastian.mail;

The application &konsole; Copyright © 1997-2008 &Lars.Doelle; &Lars.Doelle.mail;

This document was written by &Jonathan.Singer; &Jonathan.Singer.mail;

This document was updated for &kde; 3.4 by &Kurt.Hindenburg; &Kurt.Hindenburg.mail;

This document was updated for &kde; 4.1 by &Kurt.Hindenburg; &Kurt.Hindenburg.mail;

Originally converted to DocBook SGML by &Mike.McBride; and &Lauri.Watts;

&underFDL; &underGPL;

## Links

For more information please visit these websites:

- &konsole;'s homepage

- &konsole;'s mailing list

- &kde; on FreeBSD

- &kde; on &Solaris;

&documentation.index;