> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ericclemmons/agent-native/llms.txt
> Use this file to discover all available pages before exploring further.

# Keyboard commands

> Send keystrokes, shortcuts, and paste content to macOS applications

Keyboard commands send keyboard input directly to applications without targeting specific UI elements.

## key

Send keystrokes and keyboard shortcuts to an application.

```bash theme={null}
agent-native key <app> <keys...> [options]
```

### Arguments

<ParamField path="app" type="string" required>
  Application name or bundle identifier
</ParamField>

<ParamField path="keys" type="string[]" required>
  Keys to send - can be plain text, special keys, or modifier combinations
</ParamField>

### Options

<ParamField query="--json" type="boolean">
  Output as JSON
</ParamField>

### Examples

<CodeGroup>
  ```bash Type text theme={null}
  agent-native key Safari "Hello world"
  ```

  ```bash Send shortcut theme={null}
  agent-native key Safari cmd+t
  ```

  ```bash Multiple shortcuts theme={null}
  agent-native key Safari cmd+a cmd+c
  ```

  ```bash Special keys theme={null}
  agent-native key Terminal return tab escape
  ```

  ```bash Mixed input theme={null}
  agent-native key Safari cmd+k "github.com" return
  ```
</CodeGroup>

### Output

```bash theme={null}
OK Sent keys to Safari: cmd+t
```

## Keyboard syntax

### Plain text

Text without modifiers is typed character by character:

```bash theme={null}
agent-native key Safari "example@email.com"
```

### Modifier combinations

Combine modifiers with `+`:

<ParamField path="cmd" type="modifier">
  Command key (⌘)
</ParamField>

<ParamField path="ctrl" type="modifier">
  Control key (⌃)
</ParamField>

<ParamField path="alt" type="modifier">
  Option/Alt key (⌥)
</ParamField>

<ParamField path="shift" type="modifier">
  Shift key (⇧)
</ParamField>

```bash theme={null}
# Command+T (new tab)
agent-native key Safari cmd+t

# Control+A (start of line)
agent-native key Terminal ctrl+a

# Option+Delete (delete word)
agent-native key Safari alt+delete

# Shift+Tab (reverse tab)
agent-native key MyApp shift+tab

# Multiple modifiers
agent-native key Safari cmd+shift+t  # Reopen closed tab
agent-native key Safari cmd+alt+i     # Web Inspector
```

### Special keys

<Tabs>
  <Tab title="Navigation">
    * `return` / `enter` - Return/Enter key
    * `tab` - Tab key
    * `escape` / `esc` - Escape key
    * `space` - Space bar
    * `left` - Left arrow
    * `right` - Right arrow
    * `up` - Up arrow
    * `down` - Down arrow
    * `home` - Home key
    * `end` - End key
    * `pageup` - Page Up
    * `pagedown` - Page Down
  </Tab>

  <Tab title="Editing">
    * `delete` / `backspace` - Delete/Backspace
    * `forwarddelete` - Forward Delete (Fn+Delete)
  </Tab>

  <Tab title="Function keys">
    * `f1` through `f12` - Function keys
  </Tab>
</Tabs>

```bash theme={null}
# Navigation
agent-native key Safari return
agent-native key Terminal tab tab
agent-native key MyApp escape

# Arrows
agent-native key Safari down down return

# Editing
agent-native key Safari cmd+a delete

# Function keys
agent-native key Safari cmd+shift+f12
```

### Modifier aliases

Multiple aliases are supported:

* Command: `cmd`, `command`
* Control: `ctrl`, `control`
* Option: `alt`, `option`, `opt`
* Shift: `shift`

```bash theme={null}
# These are equivalent
agent-native key Safari cmd+k
agent-native key Safari command+k

# These are equivalent
agent-native key Safari alt+left
agent-native key Safari option+left
agent-native key Safari opt+left
```

## Common shortcuts

### Text editing

```bash theme={null}
# Select all
agent-native key Safari cmd+a

# Copy
agent-native key Safari cmd+c

# Cut
agent-native key Safari cmd+x

# Paste
agent-native key Safari cmd+v

# Undo
agent-native key Safari cmd+z

# Redo
agent-native key Safari cmd+shift+z

# Find
agent-native key Safari cmd+f
```

### Window management

```bash theme={null}
# New window
agent-native key Safari cmd+n

# New tab
agent-native key Safari cmd+t

# Close window/tab
agent-native key Safari cmd+w

# Close all
agent-native key Safari cmd+alt+w

# Minimize
agent-native key Safari cmd+m

# Hide app
agent-native key Safari cmd+h

# Quit
agent-native key Safari cmd+q
```

### Browser-specific

```bash theme={null}
# Address bar
agent-native key Safari cmd+l

# Reload
agent-native key Safari cmd+r

# Hard reload
agent-native key Safari cmd+shift+r

# Back
agent-native key Safari cmd+left

# Forward
agent-native key Safari cmd+right

# Next tab
agent-native key Safari ctrl+tab

# Previous tab
agent-native key Safari ctrl+shift+tab

# Reopen closed tab
agent-native key Safari cmd+shift+t
```

***

## paste

Paste clipboard contents or file contents into an application.

```bash theme={null}
agent-native paste <app> [path] [options]
```

### Arguments

<ParamField path="app" type="string" required>
  Application name or bundle identifier
</ParamField>

<ParamField path="path" type="string">
  Optional file path to paste. If omitted, pastes current clipboard or stdin.
</ParamField>

### Options

<ParamField query="--json" type="boolean">
  Output as JSON
</ParamField>

### Examples

<CodeGroup>
  ```bash Paste clipboard theme={null}
  agent-native paste Safari
  ```

  ```bash Paste file theme={null}
  agent-native paste Slack screenshot.png
  ```

  ```bash Paste from stdin theme={null}
  cat image.png | agent-native paste Slack
  ```

  ```bash Paste with tilde expansion theme={null}
  agent-native paste Arc ~/Downloads/report.pdf
  ```
</CodeGroup>

### Output

```bash theme={null}
OK Pasted screenshot.png into Slack
```

## Paste modes

### Mode 1: Paste current clipboard

```bash theme={null}
# Copy something externally, then paste
agent-native paste Safari
```

Pastes whatever is currently on the system clipboard.

### Mode 2: Paste file from path

```bash theme={null}
agent-native paste Slack /path/to/image.png
```

Copies the file to clipboard, then pastes it into the app.

### Mode 3: Paste from stdin pipe

```bash theme={null}
cat document.txt | agent-native paste Notes
echo "Hello" | agent-native paste Terminal
```

Reads data from stdin, copies to clipboard, then pastes.

## File type handling

### Image files

Images are added to clipboard in both PNG and TIFF formats:

```bash theme={null}
agent-native paste Slack screenshot.png
agent-native paste Messages photo.jpg
agent-native paste Preview diagram.gif
```

Supported formats:

* PNG (`.png`)
* JPEG (`.jpg`, `.jpeg`)
* GIF (`.gif`)
* TIFF (`.tiff`, `.tif`)
* BMP (`.bmp`)
* WebP (`.webp`)

### Other files

Non-image files are added as file URLs:

```bash theme={null}
agent-native paste Finder document.pdf
agent-native paste Slack report.xlsx
agent-native paste Messages video.mp4
```

The receiving application determines how to handle the file.

## Workflow examples

### Fill form and submit

```bash theme={null}
# Focus email field
agent-native focus @n5

# Type email
agent-native key MyApp "user@example.com" tab

# Type password
agent-native key MyApp "mypassword" return
```

### Navigate and search

```bash theme={null}
# Open new tab
agent-native key Safari cmd+t

# Focus address bar
agent-native key Safari cmd+l

# Type URL
agent-native key Safari "github.com" return

# Wait for page load
agent-native wait Safari --role TextField --label "Search" --timeout 10

# Search
agent-native key Safari cmd+f
agent-native key Safari "repository"
```

### Copy and paste between apps

```bash theme={null}
# Get text from one app
TEXT=$(agent-native get text Safari --role StaticText --label "Title")

# Activate target app
agent-native key Notes cmd+n

# Type it in
agent-native key Notes "$TEXT"
```

### Upload file

```bash theme={null}
# Click upload button
agent-native click @n10

# Wait for file dialog
agent-native wait MyApp --role Button --title "Choose" --timeout 5

# Type file path
agent-native key MyApp cmd+shift+g
agent-native key MyApp "/path/to/file.pdf" return

# Confirm selection
agent-native key MyApp return
```

### Send message with attachment

```bash theme={null}
# Focus message field
agent-native focus Slack --role TextArea --label "Message"

# Type message
agent-native key Slack "Here's the screenshot:"

# Paste image
agent-native paste Slack screenshot.png

# Wait briefly
sleep 0.5

# Send
agent-native key Slack cmd+return
```

### Terminal automation

```bash theme={null}
# Send commands
agent-native key Terminal "cd ~/projects" return
agent-native key Terminal "git status" return

# Wait for prompt (you may need to parse output)
sleep 1

# Run tests
agent-native key Terminal "npm test" return
```

### Multi-step keyboard navigation

```bash theme={null}
# Open preferences
agent-native key MyApp cmd+comma

# Navigate tabs
agent-native key MyApp tab tab tab

# Move through options
agent-native key MyApp down down

# Select
agent-native key MyApp space

# Apply
agent-native key MyApp return

# Close
agent-native key MyApp cmd+w
```

## Tips

<Tip>
  The app is automatically activated before sending keys, so you don't need to focus it manually.
</Tip>

<Tip>
  For complex input, consider using `fill` command on specific text fields instead of typing with `key`.
</Tip>

<Tip>
  Use `paste` for large amounts of text or binary data like images instead of trying to type it.
</Tip>

<Warning>
  Keyboard events are sent to the app, not specific elements. Make sure the correct element has focus.
</Warning>

<Note>
  There's a small delay (50ms) between each key argument to ensure proper processing.
</Note>

## Related commands

* [`fill`](/commands/interaction#fill) - Fill text fields directly
* [`type`](/commands/interaction#type) - Type into specific elements
* [`focus`](/commands/interaction#focus) - Set keyboard focus
* [`click`](/commands/interaction#click) - Click buttons