---
Title: General
weight: 1
feed_url: https://s3.tynsoe.org/geektool/index.json
email_title: "GeekTool Feedback"
email: "geektool@tynsoe.org"
---
# Documentation

![geektool_main](images/geektool_main.png)

GeekTool started it's life as a software mostly used by computer scientists and geeks, hence the name.  The time passing by, I finally realized that those geeks from the beginning of GeekTool made things so cool that the that mere mortals wanted to use it as well!

GeekTool is now much easier to use by anyone, let's see what we can do with it.

## Presentation

GeekTool is a macOS application that lets you customize your desktop with great flexibility. There are four modules available that you can use for different types of informations

Currently, there are 4 kinds of geeklets :

- File
- Shell
- Image
- Web

Each one displays different kind of informations, sharing the same principles :
Geeklets are ...

- ... displayed on the desktop, between finder icons and desktop picture (though, it can be set as "Keep on top"),

- ... visible on all spaces,

- ... organized in groups, you can then choose to display or not each group,

- ... part of minimum one group named "Default Group",

- ... easy to export and share with friends.

## Quick Start Guide

To Install GeekTool, simply put the GeekTool application in your preferences folder and open it.

After that, the GeekTool settings window is opened and you can start to have fun with it.

The main area of the window shows you four kinds of modules you can use. To create your first Geeklet, just pick Shell icon for example, and drop it somewhere on your desktop.

An empty black translucid area will sit on the desktop, with the inspector palette ready for you to configure this geeklet.

Set `date` or `ls` in the Command field, and the result should be displayed in the selected window.

You can then change text color & font, alignment, etc...

![geektool_main](images/shell_properties.png)

## Logs Geeklet

If you like to know what is going on on your computer, this one is for you. It displays on your desktop live content of an arbitrary file. Its primary use is to monitor system log files like `/var/log/system.log`

Content is scrolling live with latest lines at the bottom. It handles log file rotation as well.

### Regular expressions in Logs geeklet <span class="label label-default">v3.3</span>

You can use [regular expressions](http://userguide.icu-project.org/strings/regexp) to either filter lines out of the output, or do search and replace operations.

Filter regular expressions starts with the letter `d`, followed by the regular expression to match between slashes. Any line matching the regular expression will be removed from the output.

Search and replace regular expression are more complex but very powerful, it starts with the letter `s`, followed by `/`, then the regular expression describing the pattern to look for, possibly using parenthesis for back references, followed by `/`, followed by the replacement, with back references recalled with `$1`, `$2`, etc...

**Examples**

To remove any lines containig `mdworker` :

```
d/mdworker/
```

To display the PID of the process (first number between brackets) in purple

```
s/\[(.*?)\](.*)/[^[35m$1^[0m]$2/
```


You can insert [ANSI sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) to add colors to the text. Whenever the string `^[` appears, it is replaced by `ESC[` for easy manipulation of ANSI sequences

## Shell Geeklet

Maybe the most powerful one, it lets you display on your desktop the output of any unix shell command. If you are a command line addict, this one is for you. Looks at what people are doing with it (More references on the Wiki home page).

It handles ANSI escape color sequences so you can put some color in your script and some good shell knowledge.

Lot of usage examples can be found online

## Image Geeklet

This one has been created to display graph issued from monitoring systems like MRTG or Cacti.

Beyond that simple image display, you can slideshow images from a folder (even pick random ones), or images from public webcams on internet.

## Web Geeklet

If you feel limited by the Shell geeklet, Web is for you. You can generate HTML code that will we displayed over your desktop, or simply point to a web site.

## FAQ

**Where does GeekTool store its preferences?**

Preferences are stored in the standard macOS preferences system, which stores persistant data in `~/Library/Preferences/` files.

GeekTool's approach is to had a global preferences domain as `org.tynsoe.geektool3.plist` and per-geeklet configuration in `org.tynsoe.geeklet.<file|image|shell|web>` domain.

**How do I completely reset GeekTool**

To reset all GeekTool settings and geeklets, quit GeekTool, open a terminal window, and type the following :
```
defaults delete org.tynsoe.geektool3
defaults delete org.tynsoe.geeklet.file
defaults delete org.tynsoe.geeklet.shell
defaults delete org.tynsoe.geeklet.image
defaults delete org.tynsoe.geeklet.web
```

**How do I make the text translucent?**

The semi-transparency in text is actually a very clever trick that requires a bit of work. It is a normal script, or web keeklet, positioned *under* an image geeklet that displays a PNG representation of that part of your desktop background, created with transparency anywhere it should let thing appear beneath it.

**Where do I find examples of wha I can do with GeekTool?**

Thanks to [MacOSXTips.co.uk](http://www.macosxtips.co.uk/geeklets/), there is a huge repository over there.

