> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberdesk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Holding a Key

> Press and hold a key while performing other actions by using the key action's down parameter.

Some workflows need a keyboard modifier to be **held down while another action runs** — for example, holding `shift` while clicking to extend a selection, holding `ctrl` while clicking multiple files, or holding `alt` while scrolling to trigger an alternate gesture.

The `key` action supports an optional `down` parameter that controls whether the key is pressed, held, or released. Pair a `down=true` call with a later `down=false` call on the same key so the key never ends up stuck in the pressed state.

<Note>
  **Key syntax:** Use `+` to press keys **together** as one chord, e.g. `ctrl+a` or `alt+tab`. A chord can combine multiple modifiers (`ctrl`, `alt`, `shift`, `win`) but only one non-modifier key. Use **spaces** to press keys **one after another**, e.g. `down down down` (tap Down three times) or `ctrl+c ctrl+v`. Joining repeated or multiple non-modifier keys with `+` (e.g. `down+down+down`) is invalid — use spaces instead.
</Note>

## The `down` parameter

`down` is tri-state:

| `down` value      | Behavior                                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------- |
| omitted (default) | Full press: press the key down and release it immediately. Backwards-compatible with the normal `key` action. |
| `true`            | Press the key down and **hold it** without releasing.                                                         |
| `false`           | Release a key that was previously held with `down=true`.                                                      |

<Note>
  `down` only applies to the `key` action. It is ignored for `type` and every other action.
</Note>

## Basic usage pattern

To hold a key while performing another action:

<Steps>
  <Step title="Press the key down and hold">
    Call `key` with the key chord and `down=true`. The key stays pressed until you release it.
  </Step>

  <Step title="Perform the action">
    Call `left_click`, `mouse_move`, `scroll`, or any other action while the key is held.
  </Step>

  <Step title="Release the key">
    Call `key` again with the **same key** and `down=false` to release it.
  </Step>
</Steps>

## Example: shift-click to extend a selection

```
1. Use `left_click` at the first item's coordinates to select it.
2. Use `key` with text="shift" and down=true to press and hold Shift.
3. Use `left_click` at the last item's coordinates to extend the selection.
4. Use `key` with text="shift" and down=false to release Shift.
```

## Example: ctrl-click to toggle multi-select

```
1. Use `left_click` to select the first item.
2. Use `key` with text="ctrl" and down=true to press and hold Ctrl.
3. Use `left_click` to toggle each additional item.
4. Use `key` with text="ctrl" and down=false to release Ctrl.
```

## Example: ctrl-scroll to zoom

```
1. Use `key` with text="ctrl" and down=true to press and hold Ctrl.
2. Use `scroll` with scroll_direction="up" and scroll_amount=3 to zoom in.
3. Use `key` with text="ctrl" and down=false to release Ctrl.
```

## Guidelines

* **Always pair `down=true` with a matching `down=false`.** If you hold a modifier and forget to release it, every subsequent action in the workflow will be affected, and downstream typing or shortcuts will behave unexpectedly.
* **Release the same key you pressed.** If you pressed `shift` down, release `shift`, not `lshift` or `shiftleft`.
* **Avoid key chords with `down=true`.** `down` is designed for simple modifier keys like `shift`, `ctrl`, `alt`, and `win`. Do not use it with chords such as `ctrl+shift`.
* **Prefer the default full-press form when you don't need to hold.** If you just need `ctrl+a` as a one-shot, use `action="key"` with `text="ctrl+a"` and no `down` parameter. That's the normal behavior.
* **Take a screenshot after releasing if you need to verify the result.** The screenshot after a `down=true` call shows the screen *while the key is held*, which is usually not what you want to verify against.

## Comparison with modifier-click shortcuts

For simple modifier combinations like `ctrl+a` (select all), `ctrl+c` (copy), or `alt+tab` (switch window), keep using the default `key` action with the chord directly:

```
action="key", text="ctrl+a"
```

This presses and releases the chord in one atomic step. You only need the `down` parameter when the held key has to span **another action**, such as a click, a mouse move, or a scroll.