Computer

pragma-cli computer <command>

Computer commands talk directly to the host server. Reads work with the desktop closed; anything that clicks, types, or moves needs the Pragma window open, so the user can see and stop it. Computer use is off until enabled; see Computer use for the policy, the approvals, and the emergency stop.

A call from an agent's terminal is attributed to its tab ($PRAGMA_TAB_ID), so the sidebar and the approval prompt name the agent.

The usual loop

pragma-cli computer open Safari
pragma-cli computer inspect --app Safari --query address   # elements: s4:e0, s4:e1, …
pragma-cli computer type --element s4:e0 --text "example.com" --replace --submit
pragma-cli computer screenshot --app Safari --max-width 1280
pragma-cli computer end

Prefer element ids to coordinates. An element action (AXPress, setting a field's value) works on background windows and never moves the user's pointer. On macOS, clicks, scrolls, and keys are delivered to the target app in the background too: it is not brought to the front, and physicalCursor is false. Nothing an agent does brings its app forward: drag, and a click with no window of the app under the point, use the real pointer only when the app is already frontmost and fail with targetChanged otherwise. Keys go to the app's focused element, so pass --element to type when the field is not already focused. The output says which method ran: ax, pointer, or keys.

Call end when you are done. It releases the apps, clears the indicator, and lets other agents use those apps.

Reading

--app takes a name (Safari), bundle id, or app: id, and defaults to the frontmost app. Element ids look like s42:e12: element 12 of snapshot 42. They stay valid for a minute. A control that moved is found again by its identifier or label. One that is gone fails with elementStale and offers candidates.

Acting

--image-x/--image-y are pixels in a screenshot you took; the host maps them to the screen, so you never convert coordinates yourself.

Errors

Failures print their code and a hint. Under --json the whole typed failure goes to stderr as {"ok": false, "error": {"code", "message", "retryable", "hint", "details"}}.

Durable tasks

run and resume accept repeated --input name=value and --secret name=value, --max-steps, and --inputs-json <file-or->. The JSON form is { "inputs": { "text": "Hello" }, "secrets": { "password": "..." } }; prefer stdin for secrets so they do not enter shell history. Values are never persisted by the task engine.

Task states are running, paused, needsInput, needsApproval, completed, failed, and cancelled. Branch on the returned state, code, and resumable, including under --json: a task result is distinct from an RPC failure. end cancels your unfinished tasks and releases app leases.

Plain output says Waiting for input when the agent needs a value to type. It shows the question, the required input names, and a resume command. Supply the value to the CLI; the agent types it into the app. For navigation, provide a full URL. A request such as Open Safari and navigate to youtube asks for url instead of guessing one:

pragma-cli computer resume <task-id> --input 'url=https://www.youtube.com'

Failures show a readable reason and the task code. lowConfidence means Jev could not choose a safe next action confidently; it does not by itself mean text is missing. For a resumable task, supply a clarification with --note or the required literal text/URL with --input.

Jev steps need a System 1 key configured on this host. Limits and ambiguity return a handoff instead of free-form model actions. Common task codes are limitSteps, limitTime, limitModelCalls, lowConfidence, ambiguousTarget, stuck, modelUnavailable, and interrupted.

Pause and takeover end the CLI wait with status: "paused" and instructions to ask the user to resume. The panel's Resume unlocks the session; then resume <task-id> continues the task. Stop returns cancelled and requires the panel's Restart followed by a new run. Neither a fresh CLI call nor end bypasses a desktop pause or stop. Native input checks cancellation between events, including during long typing and drags.