# Quickstart

Canonical: https://plottypus.com/docs/quickstart

Last updated: 2026-09-23

> Five minutes with plottypus: the two surfaces, the footer, the process table and the three keys worth learning first.

Run it:

```sh
plottypus
```

It starts sampling every 500 ms and picks a layout for your window size. Nothing is written to disk until you change a setting.

## What you are looking at

A window at least 60 columns by 16 rows opens on **Work**: the machine on the left (cpu, gpu, mem, heat, net, power), the process table on the right. A smaller window opens on **Glance**, one column of graphs with no process table. `v` switches between them. See [Surfaces](https://plottypus.com/docs/surfaces).

Every panel title carries its live numbers. The body is a braille graph of the last two minutes, and every graph on screen shares that one clock, so a spike in cpu lines up with the spike in power under it.

The last row is the footer:

```text
 plottypus ≡  ? help  f filter  x kill  s settings  q quit      All normal    79% ▼ 7.3W 7h49m  7.3W  ● 500 ms
```

From the left: the main menu, the keys that work where you are, the verdict, then the power source and battery (laptops only), whole-system watts and the sampling rate. When the window narrows, the least important readings drop out whole; numbers are never cut in half.

## The first keys

| Key | Does |
| --- | --- |
| `?` | Every key for where you are |
| `/` or `f` | Filter processes by name as you type |
| `enter` | Open the selected process's details, or expand the focused panel |
| `tab`, `→` / `shift-tab`, `←` | Move focus between panels |
| `e` | Expand or collapse the focused panel |
| `x` | Ask the selected process to quit (TERM), after a confirmation |
| `s` | Settings |
| `p` | Pause: sampling stops completely until you press it again |
| `q` | Quit (inside an overlay it only closes the overlay) |

Using htop or btop muscle memory? `PLOTTYPUS_KEYS=htop plottypus` or `PLOTTYPUS_KEYS=btop plottypus`, or pick the profile in settings → keys. The full tables are on [Keys](https://plottypus.com/docs/keys).

## The mouse

Click a process to select it and double-click to open it. Click a column header to sort by it; click again to reverse. Click a panel to focus it, its `[↗]` corner to expand it and `[×]` to close. Drag the gutter between the machine and the process table to resize. Every hint in the footer is a button. `--no-mouse` turns all of it off.

## Five presets

`1` to `5` switch to a ready-made look. A preset turns the gpu, network, disk, heat and per-core switches on if listed and off if not, and sets the surface, the sort and zen mode. The power box is left as it is. The change is saved like any other setting.

| Key | Preset | Turns on |
| --- | --- | --- |
| `1` | silicon | gpu, heat, per-core bars |
| `2` | ml | gpu; processes sorted by memory |
| `3` | laptop | heat, per-core bars |
| `4` | sre | network and disk, always on Work |
| `5` | ricer | every panel on Glance, zen mode on |

`Z` toggles zen mode on its own: graphs only, no footer, no scale labels.

## Without a terminal

```sh
plottypus --diagnose                     # one verdict and its evidence
plottypus --json | jq .cpu_power         # one sample as JSON
plottypus --json-stream -i 1s --count 10 # NDJSON, one line per second
```

See [JSON output](https://plottypus.com/docs/json) and [Diagnose and doctor](https://plottypus.com/docs/diagnose-doctor).

## Flags

```text
-i, --interval <TIME>  Sampling interval: 250, 250ms, 1s, 1.5s (100ms..60s)
    --theme <NAME>     Colour theme (auto, billabong, paper, terminal, ...)
    --surface <NAME>   Start on the work or glance surface
    --no-mouse         Do not capture the mouse
    --config <PATH>    Read preferences from PATH
    --print-config     Print the effective preferences and exit
    --json             Print one JSON sample and exit
    --json-stream      Print one JSON sample per interval (NDJSON)
    --count <N>        Stop --json-stream after N samples
    --procs <N>        Processes in JSON output (default 10)
    --diagnose         Print a one-line verdict with its evidence
    --demo             Play a canned 60 s session instead of this Mac
-h, --help             Print this help
-V, --version          Print the version
```

`--flag=value` works too. An unknown flag prints the usage and exits with status 2, and so does starting the dashboard without a terminal attached (one line on stderr, no escape codes). `--demo` combines with every mode except `doctor` and `license`.