Skip to main content

​
Syntax

agent-desktop key-up <combo>

​
Description

Releases a key or modifier that was previously held down with key-down. This completes the key press sequence and returns the keyboard to its normal state. Always pair key-up calls with corresponding key-down calls to avoid leaving modifiers stuck in the pressed state.

​
Parameters

​
combo
string
required
Key or modifier to release. Must match a previously held key from key-down. See Key Combo Format below for syntax.

​
Key Combo Format

​
Single Modifiers

agent-desktop key-up shift
agent-desktop key-up cmd
agent-desktop key-up ctrl
agent-desktop key-up alt

​
Single Keys

agent-desktop key-up space
agent-desktop key-up return
agent-desktop key-up a

​
Modifier Combinations

agent-desktop key-up cmd+shift
agent-desktop key-up ctrl+alt

​
Modifier Aliases

  • cmd, command → Command/Windows key
  • ctrl, control → Control key
  • alt, option → Alt/Option key
  • shift → Shift key
Keys are case-insensitive: 
agent-desktop key-up SHIFT    # Same as shift
agent-desktop key-up Cmd      # Same as cmd

​
Response

​
Success Response

{
  "version": "1.0",
  "ok": true,
  "command": "key-up",
  "data": {
    "key_up": "shift"
  }
}

​
Error Response

{
  "version": "1.0",
  "ok": false,
  "command": "key-up",
  "error": {
    "code": "INVALID_ARGS",
    "message": "Unknown modifier: 'super'",
    "suggestion": "Use cmd, ctrl, alt, or shift as modifiers"
  }
}

​
Examples

​
Release Single Modifier

# Hold shift
agent-desktop key-down shift

# Select multiple items
agent-desktop click @e5
agent-desktop click @e8

# Release shift
agent-desktop key-up shift

​
Release Multi-Modifier Combination

# Hold cmd+shift
agent-desktop key-down cmd+shift

# Perform action
agent-desktop click @e3

# Release both modifiers
agent-desktop key-up cmd+shift

​
Release After Key Hold

# Hold space for canvas panning
agent-desktop key-down space

# Drag while space is held
agent-desktop drag --from-xy 100,100 --to-xy 400,300

# Release space
agent-desktop key-up space

​
Sequential Release

Releasing keys in sequence after holding them individually: 
# Hold shift first
agent-desktop key-down shift

# Then hold cmd
agent-desktop key-down cmd

# Perform action
agent-desktop click @e7

# Release in reverse order (good practice)
agent-desktop key-up cmd
agent-desktop key-up shift

​
Error Codes

CodeDescription
INVALID_ARGSInvalid key format or unknown modifier
ACTION_FAILEDOS rejected the key-up event
PERM_DENIEDAccessibility permission not granted

​
Notes

  • Always pair with key-down: Calling key-up without a prior key-down is safe but has no effect
  • Releasing a key that isn’t currently held is a no-op (does not cause an error)
  • The command returns immediately after sending the key-up event
  • Modifiers affect all input until released, so call key-up promptly

​
Best Practices

​
Match Your key-down Calls

Release keys in the same format they were pressed: 
agent-desktop key-down cmd+shift
agent-desktop key-up cmd+shift     # Correct - releases both
Avoiding mismatched releases: 
agent-desktop key-down cmd+shift
agent-desktop key-up cmd           # shift still held!
agent-desktop key-up shift         # Now shift is released

​
Use Error Handling

Ensure key-up is called even if an error occurs: 
# Pseudo-code pattern
try:
    agent-desktop key-down shift
    agent-desktop click @e5        # might fail
    agent-desktop click @e8
finally:
    agent-desktop key-up shift     # always release

​
Release Quickly

Don’t leave modifiers held longer than necessary, as they affect all system input: 
# Good: release immediately after use
agent-desktop key-down shift
agent-desktop click @e5
agent-desktop key-up shift

# Bad: long delay with modifier held
agent-desktop key-down shift
agent-desktop wait 5000            # shift held for 5 seconds!
agent-desktop click @e5
agent-desktop key-up shift

​
Cleanup on Exit

If your automation script crashes or exits unexpectedly, manually release stuck keys: 
# Release common modifiers
agent-desktop key-up shift
agent-desktop key-up cmd
agent-desktop key-up ctrl
agent-desktop key-up alt
  • key-down — Hold a key or modifier down
  • press — Press and release a key combo in one action
  • type — Type text into a specific element

Build docs developers (and LLMs) love

Get started for freeTalk to us