Skip to main content

​
Overview

Sets keyboard focus on an element and types the specified text. The command automatically focuses the element before typing, ensuring text is entered into the correct field.

​
Syntax

agent-desktop type <ref> <text>

​
Parameters

​
ref
string
required
Element reference from snapshot (@e1, @e2, etc.)
​
text
string
required
Text to type (max 10,000 characters)

​
Response

{
  "version": "1.0",
  "ok": true,
  "command": "type",
  "data": {
    "action": "type_text",
    "ref_id": "@e5"
  }
}

​
Response Fields

​
action
string
The action performed (type_text)
​
ref_id
string
The element reference that received the text

​
Behavior

The type command:
  1. Sets focus on the element using Action::SetFocus
  2. Types text character-by-character using keyboard events
  3. Preserves existing text (appends by default)
  4. Supports all printable characters and special keys
To replace existing text: 
agent-desktop clear @e5
agent-desktop type @e5 "new text"
Or select all first: 
agent-desktop focus @e5
agent-desktop press cmd+a
agent-desktop type @e5 "replacement text"

​
Usage Examples

​
Type into Text Field

agent-desktop snapshot --app Safari -i
agent-desktop find --role textfield --name "Search"
agent-desktop type @e3 "agent-desktop documentation"
agent-desktop press return

​
Fill Form Fields

agent-desktop snapshot --app "System Settings" -i

# Username field
agent-desktop type @e5 "[email protected]"

# Password field
agent-desktop type @e8 "secure_password_123"

# Submit
agent-desktop click @e12

​
Type with Special Characters

# Type text with newlines, symbols
agent-desktop type @e3 "Line 1\nLine 2\nSpecial: @#$%"

​
Type into Code Editor

agent-desktop snapshot --app "Visual Studio Code" -i
agent-desktop type @e2 "function hello() {\n  console.log('Hello');\n}"

​
Text Handling

Character TypeBehavior
Printable charsTyped as-is
Newline (\n)Presses return key
Tab (\t)Presses tab key
Special symbolsTyped with shift if needed
EmojiSupported (Unicode)

​
Performance

  • Typing speed: ~50-100 chars/second
  • For large text (>1000 chars), use set-value for better performance
  • Max length: 10,000 characters per command

​
Error Cases

Error CodeCauseRecovery
ELEMENT_NOT_FOUNDRef doesn’t exist in current refmapRun snapshot to refresh
STALE_REFElement no longer matches saved refRun snapshot and use new ref
ACTION_FAILEDElement cannot receive keyboard focusTry set-value instead
INVALID_ARGSText exceeds 10,000 charactersSplit into smaller chunks

​
Type vs Set-Value

CommandUse CaseSpeedTriggers Events
typeMimics user typingSlowerYes (keydown, keyup)
set-valueDirect value assignmentFasterNo keyboard events
Use type when:
  • App validates input on keypress
  • Autocomplete needs to trigger
  • Keyboard shortcuts should fire
Use set-value when:
  • Large text needs to be entered quickly
  • No validation on keypress
  • Direct value assignment is acceptable

​
Notes

  • Text is appended by default; use clear first to replace
  • Focus is set automatically before typing
  • Command blocks until typing completes
  • Use clipboard-set + cmd+v for very large text
  • Supports hyphenated arguments with allow_hyphen_values

Build docs developers (and LLMs) love

Get started for freeTalk to us