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 < ap p > < keys.. . > [options]
Arguments Application name or bundle identifier
Keys to send - can be plain text, special keys, or modifier combinations
Options Examples Type text
Send shortcut
Multiple shortcuts
Special keys
Mixed input
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:
Modifier combinations Combine modifiers with +:
# 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
Editing
Function keys
return / enter - Return/Enter keytab - Tab keyescape / esc - Escape keyspace - Space barleft - Left arrowright - Right arrowup - Up arrowdown - Down arrowhome - Home keyend - End keypageup - Page Uppagedown - Page Down
delete / backspace - Delete/Backspaceforwarddelete - Forward Delete (Fn+Delete)
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 < ap p > [path] [options]
Arguments Application name or bundle identifier
Optional file path to paste. If omitted, pastes current clipboard or stdin.
Options Examples Paste clipboard
Paste file
Paste from stdin
Paste with tilde expansion
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 # Focus email field agent-native focus @n5 # Type email agent-native key MyApp "[email protected] " 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.
filltypefocusclick