# 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
2010
2011
2014
2016
2017
&Kurt.Hindenburg;
&FDLNotice;
2017-01-28
Applications 17.04

&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.

&konsole; typically runs a command shell, an application that executes commands that you type. The shell the &konsole; runs depends on your account settings. Consult your operating system documentation to know what the shell is, how to configure it and how to use it.

### Scrollback

&konsole; uses the notion of scrollback to allow users 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), &Shift;Page Down (to move forward), &Shift;Up Arrow (to move up a line) and &Shift;Down Arrow (to move down a line) keys.

The amount of scrolling using &Shift;Page Up/Down can be switched between half and full page in the Scrolling tab of the profile configuration window (use Settings Edit Current Profile... to open this window).

### 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

All new and changed profiles are saved in the user's local home folder in `$`XDG_DATA_HOME`/konsole`.

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, color 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.

Any profiles which have Show in Menu checked will be listed by their name in the File New Tab menu. There will be no submenu if only the default profile is to be shown.

### 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 mouse, the marked text is displayed in reversed color 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. Hold the &Ctrl; key and drag the selected text to the desired location.

  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 text in columns.

  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 in 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 appends a new-line. That is convenient for executing pasted command quickly, but it can be dangerous so use it with caution.

  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

  - With a text selection a submenu Search for with a list of the preferred Web Shortcuts and an option to configure web shortcuts.

  - Open File Manager

  - Set Encoding

  - Clear Scrollback

  - Adjust Scrollback...

  - Show Menu Bar, only when the menubar is hidden

  - Switch Profile

  - Edit Current Profile...

  - Close Tab

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

### Drag and Drop

If you drop a file, folder or &URL; on a &konsole; window, a context menu appears with these actions:

Drag and Drop Context Menu
Drag and Drop Context Menu

&Shift;Move Here

  Move the dropped item into the current folder. This item only appears in the context menu, if you have the rights to delete the dropped file or folder.

&Ctrl;Copy Here

  Copy the dropped item into the current folder.

&Ctrl;&Shift;Link Here

  Insert a symbolic link to the dropped item.

Paste Location

  Insert the full file path of the dropped item at the cursor.

Change Directory To

  If a folder is dropped, this action appears in the context menu and allows you to change the working folder of the &konsole; session.

&Esc;Cancel

  Break the drag and drop action.

If you press the shortcuts before releasing the &LMB; during drag and drop, no context menu appears and the actions will be executed immediately.

If you want to use the &Ctrl; key for drag and drop or disable the context menu to insert &URL;s as text by default, enable the corresponding options on the Mouse tab in the profile settings dialog.

## 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.

Alternatively you can use the shortcut &Ctrl;&Shift;M to show or hide the menubar.

#### File Menu

&Ctrl;&Shift;N File New Window

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

&Ctrl;&Shift;T File New Tab

  Opens a new tab with the default profile

  &konsole; ships with a default profile. Any new profiles added by the user will be listed in the submenu. There will be no submenu if only the default profile is to be shown.

File Clone Tab

  Attempts to clone the current tab in a new tab

&Ctrl;&Shift;S File Save Output As...

  Saves the current scrollback as a text or html file

&Ctrl;&Shift;P File Print Screen ...

  Print the current screen. By default the output is scaled to fit the size of the paper being printed on with black text color and no background. In the print dialog these options can be changed on the Output Options tab.

File Open File Manager

  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 Close Window

  Quits &konsole;

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

  If you want to get the confirmation dialog get back, delete the entry

      [Notification Messages]
      CloseAllTabs=true

  in `$`XDG_CONFIG_HOME`/konsolerc`.

#### 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

Edit Select All

  Selects all the text in current window

Edit Copy Input To All Tabs in Current Window

  Allows input from the current session to be sent simultaneously to all sessions in current window

&Ctrl;&Shift;. Edit Copy Input To Select Tabs...

  Allows input from the current session to be sent simultaneously to sessions picked by user

&Ctrl;&Shift;/ Edit Copy Input To None

  Stop sending input from current session into other sessions

Edit Send Signal

  Send the specified signal to the shell process, or other process, that was launched when the new session was started.

  Currently available signals are:

  STOP | to stop process
  CONT | continue if stopped
  HUP | hangup detected on controlling terminal, or death of controlling process
  INT | interrupt from keyboard
  TERM | termination signal
  KILL | kill signal
  USR1 | user signal 1
  USR2 | user signal 2

  Refer to your system manual pages for further details by giving the command ``man` `7 signal``.

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

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

&Ctrl;&Alt;U Edit ZModem Upload...

  Opens up a dialog to select a file to be uploaded if the required software is installed

&Ctrl;&Shift;F Edit Find...

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

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

F3 Edit Find Next

  Moves to the next search instance . If the search bar has the focus, you can use the shortcut &Enter; as well.

&Shift;F3 Edit Find Previous

  Moves to the previous search instance . If the search bar has the focus, you can use the shortcut &Shift;&Enter; as well.

#### View Menu

&Ctrl;( 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;) 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 all non-current views

&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 Current Tab

  Opens the current tab in a separate window

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

&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.

&Ctrl;+ View Enlarge Font

  Increases the text font size

&Ctrl;- View Shrink Font

  Decreases the text font size

View Set Encoding

  Sets the character encoding

View Clear Scrollback

  Clears the text in the scrollback

&Ctrl;&Shift;K View Clear Scrollback and Reset

  Clears the text in the current tab and scrollback and resets the terminal

#### Bookmarks Menu

&Ctrl;&Shift;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. Currently, &konsole; accepts the following:

  - ssh://user@host:port

  - telnet://user@host:port

#### Settings Menu

Settings Edit Current Profile...

  Opens a dialog to configure current profile

Settings Switch Profile

  Switch current profile to a listed profile

Settings Manage Profiles...

  Opens a editor for managing profiles

&Ctrl;&Shift;M Settings Show Menu Bar

  Toggles the menubar being visible

F11 Settings Full Screen Mode

  Toggles &konsole; filling the entire screen

Settings Configure Shortcuts...

  Opens the keyboard shortcut editor. More on shortcuts configuration can be found in the &kde; Fundamentals.

  Additionally &konsole; has a few special shortcuts with no corresponding menu item:

  Shortcut | Description
  --- | ---
  &Shift;Right | Next Tab
  &Shift;Left | Previous Tab
  &Ctrl;&Shift;Left | Move Tab Left
  &Ctrl;&Shift;Right | Move Tab Right
  &Ctrl;&Shift;Ins | Paste Selection
  &Shift;&Tab; | Next View Container

Settings Configure Notifications...

  Opens the notifications editor

Settings Configure &konsole;...

  Opens the &konsole; settings editor

  This dialog has options influencing the appearance and behaviour of the TabBar and general options for the &konsole; window.

#### Help Menu

&konsole; has the some of the common &kde; Help menu items, for more information read the section about the Help Menu of the &kde; Fundamentals.

### &konsole; Dialogs

#### 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 substitute these tokens for local tabs:

- %n : program name

- %d : current directory (short)

- %D : current directory (long)

- %h : local host (short)

- %u : user name

- %w : window title set by shell

- %# : session number

&konsole; will substitute these tokens for remote tabs:

- %c : current program

- %h : remote host (short)

- %H : remote host (long)

- %u : user name

- %U : user name@ (if given)

- %w : window title set by shell

- %# : session number

Examples:

- `%d : %n` with /usr/src as current directory and running bash will display src : 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.

#### Adjust Scrollback Dialog

The scrollback options for the history size can be changed in this dialog. Any changes are for the current tab only and will not be saved to the profile.

## Command-line Options

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

`--help`

  List various options.

`--profile` `file`

  Start &konsole; using the specified profile instead of the default profile.

`--fallback-profile`

  Use the internal FALLBACK profile. This option is a shortcut for `--profile` `FALLBACK/`.

`--workdir` `dir`

  Open with `dir` as the initial working directory.

`--hold, --noclose`

  Do not close the initial session automatically when it ends.

`--new-tab`

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

`--tabs-from-file` `file`

  Create tabs as specified in the given tabs configuration file.

  The file has one tab per line in the following format:

  Each line specifies a tab to open using up to 4 fields specifying how it is to open. Fields are delimited with `;;` and a field name must have a `:` appended. Empty lines or lines with `#` at the beginning are ignored, so you can use line beginning with `#` to add comments.

  - `title:` a name for this tab, tab default if blank or not specified
  - `workdir:` working directory, `~` if blank or not specified
  - `profile:` a &konsole; profile to use, the default if blank or not specified
  - `command:` a command to run

  Each line should contain at least one of `command` or `profile` field.

  Example: `title: %n;; command: /usr/bin/top ;; profile: Shell`

`--background-mode`

  Start &konsole; in the background and bring to the front when &Ctrl;&Shift;F12 (by default) is pressed.

`--separate`
`--nofork`

  Run the new instance of &konsole; in a separate process.

`--show-menubar`

  Show the menubar, overriding the default behavior.

`--hide-menubar`

  Hide the menubar, overriding the default behavior.

`--show-tabbar`

  Show the tabbar, overriding the default behavior.

`--hide-tabbar`

  Hide the tabbar, overriding the default behavior.

`--fullscreen`

  Start &konsole; in fullscreen mode.

`--notransparency`

  Disable transparent backgrounds, even if the system supports them.

`--list-profiles`

  List all available profiles.

`--list-profile-properties`

  List all possible properties with name and type. See option `-p`.

  For more information, please visit &konsole; API Reference.

`-p` `property=value`

  Change the value of a profile property.

`-e` `command`

  Execute `command` instead of the normal shell.

  This option will catch all following arguments passed to &konsole;, and execute it as `command`. So this option should always be used as the last option.

&konsole; also accepts generic &Qt; and &kf5-full; options, see man pages qt5options and kf5options.

## Scripting &konsole;

&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` will display the &DBus; interface for &konsole;.

- &percnt; `qdbus` `org.kde.konsole /Windows/1` will display methods for controlling window 1.

- &percnt; `qdbus` `org.kde.konsole $KONSOLE_DBUS_WINDOW` will display methods for controlling the current window.

- &percnt; `qdbus` `org.kde.konsole /Sessions/1` will display methods for controlling session 1.

- &percnt; `qdbus` `org.kde.konsole $KONSOLE_DBUS_SESSION` will display methods for controlling the current session.

- &percnt; `qdbus` `$KONSOLE_DBUS_SERVICE $KONSOLE_DBUS_SESSION` will display methods for controlling the current &konsole;'s session.

If any of the above commands outputs: Service 'org.kde.konsole' does not exist, change `org.kde.konsole` to one of the following:

- `org.kde.konsole-`pidof -s konsole`` (will select first pid)

- `$KONSOLE_DBUS_SERVICE` (this can be used from the current &konsole;)

- `select one from the output of 'qdbus | grep konsole'`

For more information, please visit &DBus; tutorial.

## Using Style Sheet for the Tab Bar

The default style sheet for the tab bar sets the minimum and maximum tab widths. The user can create a `.css` file and have &konsole; use that as the style sheet for the tab bar. In the `.css` file, the widget to use is `QTabBar::tab`.

For more information, consider reading &Qt; Style Sheets

Examples:

- Change the selected tab's background to a light gray

      QTabBar::tab:selected {
          background: #999999
      }

- Change the selected tab's text to red

      QTabBar::tab:selected {
          color: red
      }

- All tabs will be at least 200 pixels in width

      QTabBar::tab {
          min-width: 200px
      }

- Only the selected tab will be at least 200 pixels in width

      QTabBar::tab::selected {
          min-width: 200px
      }

- Any of these can be combined in one file

      QTabBar::tab::selected {
          background: #999999;
          color: red;
          min-width: 200px;
      }
      QTabBar::tab {
          min-width: 100px
      }

## Did You Know?, Common Issues and More

### Did You Know?

- Pressing &Ctrl; while selecting text will cause lines breaks to be converted to spaces when pasted.

- Pressing the &Ctrl;&Alt; keys while selecting text will select columns.

- The &Ctrl;Wheel combination will zoom text size, like in konqueror and firefox.

- When a program evaluates either mouse button, pressing the &Shift; key will allow the popup menu to appear.

- The &Ctrl;&Shift;F10 shortcut will activate the menu.

- The &Shift;Insert keys will insert the clipboard.

- Double-clicking will select a whole word. Continuing to hold the mouse button and moving the mouse will extend the selection.

- Triple-clicking will select a whole line. Continuing to hold the mouse button and moving the mouse will extend the selection.

- There is a hidden feature for the "%d" formatter in tab title. You can tell &konsole; to abbreviate a directory name into its first character. For example, "/path/to/konsole/src" can be abbreviated into "konsole/s". If you want to enable and control this hidden feature, open `konsolerc` in ``qtpaths` `--paths GenericConfigLocation`` and add following lines:

      [ProcessInfo]
      CommonDirNames=name1,name2,name3...

  If you are using Yakuake, you need to edit `yakuakerc` in ``qtpaths` `--paths GenericConfigLocation`` instead.

### Common Issues

- Some fonts might be unavailable for usage in &konsole;, although they are available in other applications. That doesn't mean there is a bug in &konsole;. &konsole; requires monospaced fonts to provide the best visual result, so it asks &Qt; to only list monospaced fonts.

  Starting with version 16.08 (August 2016), &konsole; can be configured to allow selecting any font with the caveat that the display may not be correct.

- Since KDE4 all the tabs use the same process ID. This has the side-effect that if one tab's process has issues, all the other tabs may experience issues as well.

  This is most noticeable when a command that connects to an external device or system (ssh, nfs) has issues.

- &konsole; treats arguments after the `-e` option as one command and runs it directly, instead of parsing it and possibly dividing it into sub-commands for execution. This is different from xterm.

  - `konsole -e "command1 ; command2"` does not work

  - `konsole -e $SHELL -c "command1 ; command2"` works

- &konsole; doesn't provide convenience for running login shell, because developers don't like the idea of running login shell in a terminal emulator.

  Of course, users still can run login shell in &konsole; if they really need to. Edit the profile in use and modify its command to the form of starting a login shell explicitly, such as "`bash -l`" and "`zsh -l`".

- The `--new-tab` option sometimes behaves strangely. It may create new window, or it may create new tab in another existing &konsole; window instead of the current &konsole; window.

  Those behaviors feel strange, but they are not necessarily bugs. The `--new-tab` option tries to reuse existing &konsole; windows, but not all &konsole; windows are reusable. All &konsole; windows opened through &krunner; are reusable, while most &konsole; windows opened from command line are not.

## Credits and Copyright

&konsole; is currently maintained by &Kurt.Hindenburg; &Kurt.Hindenburg.mail;

Previous &konsole; maintainers include: &Robert.Knight; &Robert.Knight.mail; and &Waldo.Bastian; &Waldo.Bastian.mail;

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

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

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

This document was updated for &kde; 3.4 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 on &kde;'s UserBase

- &konsole;'s homepage

- &konsole;'s mailing list

- &kde; on FreeBSD

- &kde; on &Solaris;

&documentation.index;