peekaboo set-value

set-value writes an accessibility value directly to a settable element. It is the CLI equivalent of the MCP set_value tool and avoids keyboard synthesis, cursor movement, input-method timing, and autocomplete side effects when replacement semantics are intended.

#Options

#Notes

• The target element must expose a settable accessibility value.
• A concrete --snapshot already identifies the app and window; do not combine it with target flags. Omit the concrete snapshot (or use --snapshot latest) when supplying target flags to capture a fresh targeted snapshot. Conflicts return INVALID_INPUT with a retry-safe, non-dispatched refusal before runtime discovery.
• Numeric controls retain native numeric verification, including floating-point rounding tolerance; numeric-looking

text remains literal. Successful output reports the observed value, not a replacement copy of the requested value.

• Boolean verification requires an actual Boolean or exact numeric 0/1; fractional values are not truncated.
• Integer-valued controls accept decimal strings and decimal/scientific forms such as 001.0, 10e-1, and 1.e3

only when they represent an exact in-range integer. Nonzero fractional tails, underflow-to-zero, out-of-range values, and hexadecimal forms are rejected before writing. These restrictions do not apply to literal text controls.

• Every mutation requires a current snapshot. App/PID/window target flags capture one automatically; without target

flags, run peekaboo see first. A missing snapshot is refused instead of falling through to the frontmost app. Exact process/window receipts and the final resolved Accessibility element PID are revalidated before the value is written.

• Remote value mutation requires Bridge protocol 1.37 and processGenerationBoundElementMutations; older or

receiptless hosts are refused before the request is sent.

• Current clients negotiate typed value-verification evidence with capable hosts. Without that evidence, remote

results retain the legacy exact-string verification contract.

• A result with requires_fresh_observation: true, or no canonical outcome, makes that snapshot mutation-ineligible.

The old evidence stays readable, but another mutation must use a new peekaboo see snapshot and otherwise fails before dispatch.

• Accepted writes are observed for up to 250 ms to allow apps to publish asynchronous Accessibility updates. Each

sample revalidates the original field and process generation; the write is never repeated.

• Native samples batch non-value identity metadata to reduce AX round trips, while still checking identity before

and after reading the value. Unsupported, malformed or generically failed batches retain bounded single-attribute reads within the original deadline. The observation budget and security checks are unchanged; batching is not an atomic-state guarantee.

• If the Accessibility write is accepted but its readback cannot be verified, Peekaboo reports an indeterminate,

retry-unsafe result with the exact target receipt. Observe the target again before deciding whether to retry; never replay the write against the old snapshot.

• Post-write native value samples require readable security metadata. If AXSubrole is unreadable, the reader skips

the potentially sensitive value; it never falls back to events or replays the accepted write to force confirmation. A later readable sample can confirm within the existing 250 ms budget. Otherwise the result stays indeterminate and retry-unsafe. Known absent subroles (noValue or attributeUnsupported) remain supported; this does not change the separate pre-dispatch value-reading policy.

• Secure/password fields are rejected; use explicit typing flows for those contexts.
• This is not a replacement for peekaboo type when the app needs observable keystrokes, IME handling, autocomplete, or undo grouping.
• JSON and MCP output includes the canonical process-generation target_identity and target_receipt alongside

target, actionName, oldValue, newValue, and executionTime.

#Examples

peekaboo see --app TextEdit
peekaboo set-value "hello" --on "$ELEMENT_ID" --snapshot <snapshot-id>

peekaboo set-value "42" --on "Search"