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.

agent-native key <app> <keys...> [options]

Arguments

app · string · required

Application name or bundle identifier

keys · string[] · required

Keys to send - can be plain text, special keys, or modifier combinations

Options

--json · boolean

Output as JSON

Examples

Type text

agent-native key Safari "Hello world"

Output

OK Sent keys to Safari: cmd+t

Keyboard syntax

Plain text

Text without modifiers is typed character by character:

agent-native key Safari "[e-mail]"

Modifier combinations

Combine modifiers with +:

cmd · modifier

Command key (⌘)

ctrl · modifier

Control key (⌃)

alt · modifier

Option/Alt key (⌥)

shift · modifier

Shift key (⇧)

# 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

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

Editing

• delete / backspace - Delete/Backspace
• forwarddelete - Forward Delete (Fn+Delete)

Function keys

• f1 through f12 - Function keys

# 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

# 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

# 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

# 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

# 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.

agent-native paste <app> [path] [options]

Arguments

app · string · required

Application name or bundle identifier

path · string

Optional file path to paste. If omitted, pastes current clipboard or stdin.

Options

--json · boolean

Output as JSON

Examples

Paste clipboard

agent-native paste Safari

Output

OK Pasted screenshot.png into Slack

Paste modes

Mode 1: Paste current clipboard

# Copy something externally, then paste
agent-native paste Safari

Pastes whatever is currently on the system clipboard.

Mode 2: Paste file from path

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

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:

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:

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

# Focus email field
agent-native focus @n5

# Type email
agent-native key MyApp "[e-mail]" tab

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

Navigate and search

# 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

# 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

# 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

# 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

# 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

# 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

The app is automatically activated before sending keys, so you don’t need to focus it manually.

For complex input, consider using fill command on specific text fields instead of typing with key.

Use paste for large amounts of text or binary data like images instead of trying to type it.

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

There’s a small delay (50ms) between each key argument to ensure proper processing.

Related commands

• fill - Fill text fields directly
• type - Type into specific elements
• focus - Set keyboard focus
• click - Click buttons