Skip to content
UmbraUmbra

Quickstart

View as Markdown

This walks you from a fresh install to a desktop you’ve arranged yourself.

1. Add widgets

Section titled “1. Add widgets”

Click the Umbra icon in the tray (the notification area next to the clock), or open Umbra from the Start menu, to open Settings. Go to Browse and click Install on a few widgets: Clock, Weather and To Do are a good start. Each card lists exactly what the widget can reach (for example api.open-meteo.com, or No network access), so you know what you’re installing.

New widgets appear on your desktop at once, each in its default position.

2. Arrange them

Section titled “2. Arrange them”

Open the tray menu and choose Edit mode (or turn it on from My widgets). Every unlocked widget gets an outline and a corner handle:

  • Drag a widget to move it. Guide lines show when it lines up with an edge, a center or a neighbour. Hold Shift while dragging to skip snapping.
  • Drag the corner (or hold Ctrl and scroll) to resize. Widgets zoom like a web page, so text stays sharp.
  • Click a widget to select it, then nudge it with the arrow keys: 1 px, or 10 px with Shift.

A small Editing widgets · Snap · Done pill appears at the top of each monitor that has widgets. Click Done (or press Esc on a clicked widget) to leave edit mode. See Arranging widgets for everything edit mode can do.

3. Make them yours

Section titled “3. Make them yours”

In My widgets, each widget has its own card: change its options (a city, a currency, a time format), its size, its opacity, and when it should be visible. Under General you can set the accent color, corner radius and fonts, and Themes switches the whole look in one click. All changes apply live.

4. Peek and show the desktop

Section titled “4. Peek and show the desktop”

Press Win+D: your widgets stay where they are. To bring them above your apps for a few seconds without moving anything, use Peek. Assign hotkeys for it, for edit mode, for refresh and for show/hide in Settings → Hotkeys (details).

5. Try the command line

Section titled “5. Try the command line”

The installer puts umbractl on your PATH. Every command prints JSON, and starts Umbra in the background if it isn’t running:

Terminal window
umbractl list                          # your widgets, options and positions
umbractl install sp500                 # install from the catalog
umbractl set sp500 symbol ^IXIC        # follow the Nasdaq instead; applies instantly
umbractl configure sp500 --scale 1.5   # 150 % size
umbractl capture sp500 shot.png        # a PNG of just that widget

The command reference lists every command.

6. Build your own

Section titled “6. Build your own”
Terminal window
umbractl new my-widget

This creates a working widget in %APPDATA%\Umbra\widgets\my-widget and shows it on your desktop. Edit its files, run umbractl reload, and follow Your first widget.