# Shortcuts (/features/shortcuts)



A shortcut is a **trigger** and an **action**, plus an optional name, an
optional scope, and a switch. Rows live in the **Shortcuts** pane — the one
settings opens on — and a row is live the moment it is saved. There is no apply
step and no restart.

[Your first shortcut](/get-started/first-shortcut) walks through adding and
saving one. This page is the reference: every action, and what an empty field
falls back to.

<Screenshot name="shortcuts-pane" alt="The Shortcuts pane" />

## Triggers [#triggers]

Most shortcuts are a **chord** — a modifier or two and a key, recorded by
clicking the trigger field and pressing it. Two other kinds of trigger are
recorded the same way:

* **Double tap** — two taps of a lone modifier (⇧, ⌃, ⌥, ⌘, or a Fn), nothing
  else held. The mechanism, and how fast the two taps must be, lives in its own
  pane; the binding is an ordinary row here. See [below](#double-tap-and-fn).
* **Fn** — a combination that includes the Fn (globe) key. macOS never lets an
  application register one, so Lumi matches these itself on the way past. That
  is also why **Test** is greyed out for a Fn or double-tap trigger: there is no
  OS claim to make, so nothing another app could be holding.

A chord already taken by another row, or one macOS refuses outright, is
reported the moment you press it — not held back to Save. Everything else about
a half-filled row waits for Save.

## The actions [#the-actions]

The picker groups them the way the app does. Open it and type to filter.

<Screenshot name="action-picker" alt="The action picker" />

### Apps [#apps]

| Action          | Fields                                            | An empty field means                               |
| --------------- | ------------------------------------------------- | -------------------------------------------------- |
| **Open app**    | The application                                   | — (Save asks for one)                              |
| **Toggle app**  | The application; **Open it if it is not running** | Switch on: launch it. Off: do nothing, and say so. |
| **Open URL**    | The URL or `x-apple.systempreferences:…` link     | —                                                  |
| **Run command** | Program path; arguments                           | No arguments                                       |

**Toggle app** is one key for both directions: press it and the app comes
forward, press it again while you are looking at it and it hides — `⌘H`, the
whole application, not the front window minimised. Coming back takes the same
three steps **Focus** does, so an app hidden with `⌘H` or left with its windows
in the Dock arrives showing something. That last part needs
[Accessibility](/get-started/permissions); without it the toggle still hides and
shows.

### Windows [#windows]

| Action             | Fields                                                                                                | Notes                                                                                |
| ------------------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **Arrange window** | A slot (halves, thirds, quarters, maximise, centre, restore); how to treat a window that will not fit | Moves and resizes the frontmost window on its display.                               |
| **Cycle windows**  | Direction — **Next** or **Previous**                                                                  | macOS's <kbd>⌘</kbd><kbd>\`</kbd> on a key you choose. Follows whatever is in front. |

Next and Previous are exact inverses: three of each and you are back where you
started. Minimised windows and non-standard windows (sheets, palettes) are
skipped. With one window or none, nothing happens and nothing is said — but the
press **is** refused, out loud, without Accessibility.

### Input [#input]

| Action             | Fields                                                   | An empty field means |
| ------------------ | -------------------------------------------------------- | -------------------- |
| **Send keystroke** | The combination to synthesise                            | —                    |
| **Type text**      | The text; may hold [variables](/features/variables)      | —                    |
| **Media control**  | Play/pause, next, previous, volume up, volume down, mute | Play/pause           |

**Send keystroke** presses a combination into the front app — a menu item with
no shortcut of its own, an editor command. **Type text** inserts a string at
the caret; because it renders variables, `{{$date}}` or `{{$selectedText}}` in
the text is filled in fresh each press.

### Cursor [#cursor]

| Action            | Fields                                                                                                     | An empty field means           |
| ----------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------ |
| **Move cursor**   | Target (a display, the pointer's display, the frontmost window); how it lands (centre, keep relative spot) | The pointer's display, centred |
| **Cursor effect** | Ripple, spotlight or halo; size; colour; duration; for a spotlight, whether it is a flash or a held toggle | A medium red ripple            |

### System [#system]

| Action                   | Fields                                      | An empty field means |
| ------------------------ | ------------------------------------------- | -------------------- |
| **System command**       | One of eleven — see below                   | Lock screen          |
| **Open System Settings** | One of thirty-nine panes, with a search box | Displays             |

**System command** covers lock screen, start screen saver, switch user, sleep,
turn display off, and log out / restart / shut down. The last three come in a
pair each — one hands the request to macOS and lets it put up its own
confirmation sheet, the other fires at once — and those three also need the
separate [Automation permission](/get-started/permissions#automation-for-three-system-commands).
Pick the asking one unless you have a reason not to.

**Open System Settings** stores the pane by a name of Lumi's own (`displays`,
`sound`), not Apple's identifier, so a shortcut saved today survives the next
time Apple renames them. A pane not on the list is still reachable through
**Open URL** with its `x-apple.systempreferences:…` link.

### Lumi [#lumi]

| Action         | Fields                                                 | Notes                                                                               |
| -------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| **Show alert** | The text; optionally a style overriding the global one | Text may hold [variables](/features/variables).                                     |
| **Run flow**   | The flow                                               | Offered only for a flow with a Manual trigger — see [Flows](/features/flows).       |
| **Open menu**  | The menu (created empty); an optional timeout override | A [leader menu](/features/leader-menus). Steps are added by looking inside the row. |

## Naming a row [#naming-a-row]

A row you do not name describes itself from what it does — `Toggle app ·
Calculator`, `Open menu · 4 steps`. Type a name to override that. The picker to
the left of the field sets the row's icon; left alone it follows the action, and
on a [leader menu](/features/leader-menus) step it is what the cheatsheet draws
beside the key.

The Name field takes two [variables](/features/variables) and no others:
`{{$clipboardText}}` and `{{$selectedText}}`. On a [leader menu](/features/leader-menus)
step, `Paste: {{$clipboardText}}` shows what a key is about to paste, on the
cheatsheet, before you press it. The Shortcuts list itself shows the name as
written — a title that changed with your clipboard is a row you could not find
again.

## Scope [#scope]

**Runs in** limits a shortcut to one application, or leaves it global. A global
row and a scoped row may share a combination; two globals may not, and two
scoped rows collide only when they name the same app.

<Screenshot name="shortcut-scope" alt="The Runs in picker" />

Scope is not offered on a leader menu step: a menu freezes the front
application when it opens, so a step scoped differently would either do nothing
or contradict the cheatsheet it sits on.

## Double tap and Fn [#double-tap-and-fn]

Two taps of a modifier is a trigger like any chord, bound here in the Shortcuts
pane. The **Double tap** pane owns the mechanism: whether it runs at all, and
the timing — how long the first tap may be held and how quickly the second must
follow — shared across keys or calibrated per key.

<Screenshot name="double-tap-pane" alt="The Double tap pane" />

A modifier cannot be swallowed without macOS believing it is stuck down, so an
application with a double-modifier trick of its own fires alongside yours.

Fn combinations need no pane — the `Fn+` in the trigger is the whole of it.

## Three rules the editor plays by [#three-rules-the-editor-plays-by]

Covered in full under [Your first shortcut](/get-started/first-shortcut):

* **Save is when a form is checked.** The button is always enabled; press it
  with something missing and the error appears under the offending field.
* **A row that fails says so twice** — an alert for two seconds, and the reason
  pinned to the row.
* **Disabled is not deleted.** A row that is off claims nothing; the
  combination is free for something else, and turning it back on re-registers
  it.