SPB Git

Repository Public License

tools.md 49.3 KB

# Tool reference

Generated by orixctl tools --markdown from the registered tool manifests (77 tools). Do not edit by hand.

# accessibility

# accessibility.find

Finds interface elements of a running application by role, title, identifier or value and returns their stable paths for the action tools.

  • side effect: read
  • default tier: 0
  • timeout: 60 s
  • idempotent
  • output is untrusted data
  • macOS permission: accessibility
Argument Type Required Description
bundleID string yes Application bundle identifier, for example com.apple.finder.
identifier string Exact accessibility identifier.
includeMenuBar boolean Search the menu bar too (default false).
maxDepth integer Search depth (default 30).
maxResults integer Maximum matches returned (default 20).
role string Accessibility role or subrole, for example AXButton, AXTextField, AXMenuItem.
title string Case-insensitive substring of the element's title or description.
value string Case-insensitive substring of the element's value (never matches secure fields).

Output fields: matches, searched, truncated

# accessibility.focus

Brings a running application to the front and gives keyboard focus to one of its elements, then verifies both. Call before accessibility.typeText.

  • side effect: write
  • default tier: 2
  • timeout: 15 s
  • idempotent
  • output is untrusted data
  • macOS permission: accessibility
Argument Type Required Description
activate boolean Bring the application to the front first (default true).
bundleID string yes Application bundle identifier, for example com.apple.finder.
element string yes Element path returned by accessibility.tree or accessibility.find, for example AXApplication/AXWindow[0]/AXButton[2].
expectedTitle string Optional title or description the element must still have; the action is refused if it changed.

Output fields: element, focused, frontmost

# accessibility.press

Presses a button, menu item or other pressable element of a running application through the Accessibility API (no pointer movement). The element is re-resolved from its path right before the action.

  • side effect: write
  • default tier: 2
  • timeout: 15 s
  • dry run: yes
  • output is untrusted data
  • macOS permission: accessibility
Argument Type Required Description
bundleID string yes Application bundle identifier, for example com.apple.finder.
element string yes Element path returned by accessibility.tree or accessibility.find, for example AXApplication/AXWindow[0]/AXButton[2].
expectedTitle string Optional title or description the element must still have; the action is refused if it changed.

Output fields: element, pressed

# accessibility.setValue

Sets the value of a text field, checkbox, slider or similar element of a running application, then reads it back. Secure text fields are refused.

  • side effect: write
  • default tier: 2
  • timeout: 15 s
  • dry run: yes
  • output is untrusted data
  • macOS permission: accessibility
Argument Type Required Description
bundleID string yes Application bundle identifier, for example com.apple.finder.
element string yes Element path returned by accessibility.tree or accessibility.find, for example AXApplication/AXWindow[0]/AXButton[2].
expectedTitle string Optional title or description the element must still have; the action is refused if it changed.
value string or number or boolean yes New value.

Output fields: element, set, verified

# accessibility.status

Reports whether this app is trusted for Accessibility control and how the user can enable it. Never prompts.

  • side effect: read
  • default tier: 0
  • timeout: 5 s
  • idempotent

Output fields: howToEnable, settingsURL, trusted

# accessibility.tree

Lists the interface elements of a running application (role, title, value, enabled, frame, stable path). Values of secure text fields are replaced by «secure».

  • side effect: read
  • default tier: 0
  • timeout: 60 s
  • idempotent
  • output is untrusted data
  • macOS permission: accessibility
Argument Type Required Description
bundleID string yes Application bundle identifier, for example com.apple.finder.
element string Optional path of the element to start from (default: the application).
includeMenuBar boolean Include the menu bar (default false).
maxDepth integer How deep to go below the start element (default 6).
maxNodes integer Maximum elements returned (default 300).

Output fields: application, nodes, truncated

# accessibility.typeText

Types text as keyboard events into one element of the frontmost application. Refused unless that application is in front and that element has keyboard focus (checked again before every chunk), and always refused for secure text fields.

  • side effect: write
  • default tier: 2
  • timeout: 60 s
  • dry run: yes
  • output is untrusted data
  • macOS permission: accessibility
Argument Type Required Description
bundleID string yes Application bundle identifier, for example com.apple.finder.
element string yes Element path returned by accessibility.tree or accessibility.find, for example AXApplication/AXWindow[0]/AXButton[2].
expectedTitle string Optional title or description the element must still have; the action is refused if it changed.
text string yes Text to type. Newlines press Return, tabs press Tab.

Output fields: element, typedCharacters

# accessibility.waitFor

Polls a running application's interface until an element exists, disappears, becomes enabled or focused, or shows a given value. Use it to confirm the effect of an action instead of sleeping.

  • side effect: read
  • default tier: 0
  • timeout: 120 s
  • idempotent
  • output is untrusted data
  • macOS permission: accessibility
Argument Type Required Description
bundleID string yes Application bundle identifier, for example com.apple.finder.
condition string What to wait for (default exists).
element string Element path to watch, as an alternative to the role/title/identifier/value filters.
expected string Expected value for valueEquals / valueContains.
identifier string Exact accessibility identifier.
pollIntervalMs integer Polling interval (default 200).
role string Accessibility role or subrole, for example AXButton, AXTextField, AXMenuItem.
timeoutSeconds number How long to wait (default 10).
title string Case-insensitive substring of the element's title or description.
value string Case-insensitive substring of the element's value (never matches secure fields).

Output fields: condition, elapsedMs, satisfied

# applescript

# applescript.dictionary

Summarises an application's AppleScript/JXA scripting dictionary (suites, commands with parameters, classes with properties). Reports unsupported when the application is not scriptable.

  • side effect: read
  • default tier: 0
  • timeout: 30 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
bundleID string Application bundle identifier, for example com.apple.finder.
maxItems integer Maximum commands and classes returned per suite (default 60).
path string Path of the application bundle, as an alternative to bundleID.

Output fields: application, classCount, commandCount, path, suites

# applescript.run

Runs AppleScript source out of process and returns its result. Every application the script addresses must be listed in targets (bundle identifiers); a script with no target only computes. Shell, Objective-C bridge and file access from the script need the bash runtime grant.

  • side effect: external
  • default tier: 2
  • timeout: 120 s
  • dry run: yes
  • output is untrusted data
  • macOS permission: appleEvents
Argument Type Required Description
script string yes The AppleScript source text.
targets array Bundle identifiers of every application the script talks to. Empty for pure computation.
timeoutSeconds number Maximum run time in seconds (default 30).

Output fields: language, parsed, result, stderr, targets, value

# jxa.run

Runs JavaScript for Automation source out of process and returns its result. Every application the script addresses must be listed in targets (bundle identifiers); a script with no target only computes. Shell, Objective-C bridge and file access from the script need the bash runtime grant.

  • side effect: external
  • default tier: 2
  • timeout: 120 s
  • dry run: yes
  • output is untrusted data
  • macOS permission: appleEvents
Argument Type Required Description
script string yes The JavaScript for Automation source text.
targets array Bundle identifiers of every application the script talks to. Empty for pure computation.
timeoutSeconds number Maximum run time in seconds (default 30).

Output fields: language, parsed, result, stderr, targets, value

# browser

# browser.click

Click an element of the open page by CSS selector, after checking that it exists, is visible and is enabled. Waits for any navigation that follows and reports it. A navigation to a host the run was not granted is blocked.

  • side effect: external
  • default tier: 2
  • timeout: 60 s
  • output is untrusted data
Argument Type Required Description
selector string yes CSS selector of the element, as returned by browser.read.
timeoutSeconds number Give up waiting for a navigation after this many seconds.

Output fields: clicked, dialogs, navigated, selector, status, title, url

# browser.close

Close the ORIX browser session of this run and discard its cookies and page state.

  • side effect: write
  • default tier: 0
  • timeout: 10 s
  • idempotent

Output fields: closed

# browser.download

Download a file with the ORIX browser's session (its cookies apply) into the run's artifacts folder or a given path, with a size cap. Returns the path, size and SHA-256. Pages never start downloads on their own.

  • side effect: external
  • default tier: 2
  • timeout: 600 s
  • output is untrusted data
Argument Type Required Description
maxBytes integer Refuse anything larger. Default 52428800 (50 MB).
overwrite boolean Replace an existing file. Default false.
path string Where to save it. Default: downloads/ in the run's artifacts folder.
timeoutSeconds number Give up after this many seconds.
url string yes Absolute https URL of the file.

Output fields: bytes, mimeType, path, sha256, status, suggestedFilename, url

# browser.fill

Set the value of a form control on the open page (text field, textarea, select by option value or label, checkbox or radio) and dispatch input/change events. Password and payment-card fields only accept secretRef, the name of a stored secret, so the value never passes through a model.

  • side effect: external
  • default tier: 2
  • timeout: 20 s
Argument Type Required Description
checked boolean For a checkbox or radio button: the state to set.
secretRef string Reference name of a stored secret to enter instead of a value.
selector string yes CSS selector of the field, as returned by browser.read.
value string Text to enter, or the option to select.

Output fields: filled, secure, selector, tag, type, valueLength

# browser.open

Open a URL in the ORIX browser (a private WebKit view with no access to Safari's cookies) and wait for the page to load. Returns the final URL, HTTP status and title. Only https, or http on this Mac's loopback.

  • side effect: external
  • default tier: 1
  • timeout: 60 s
  • output is untrusted data
Argument Type Required Description
timeoutSeconds number Give up after this many seconds.
url string yes Absolute https URL.

Output fields: dialogs, redirected, status, title, url

# browser.read

Read the page currently open in the ORIX browser as structured data: title, URL, visible text, headings, links, forms with their fields, buttons and tables. Every interactive element comes with a CSS selector that browser.fill, browser.click and browser.waitFor accept. Password and payment-card values are never returned.

  • side effect: read
  • default tier: 0
  • timeout: 20 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
maxBytes integer Upper bound for the visible text, in bytes.
maxItems integer Upper bound for each list (links, fields, buttons…).

Output fields: buttons, dialogs, fields, forms, headings, links, tables, text, title, truncated, url

# browser.screenshot

Save a PNG picture of the visible part of the open page. Without a path the file goes to the run's artifacts folder.

  • side effect: write
  • default tier: 1
  • timeout: 30 s
  • output is untrusted data
Argument Type Required Description
overwrite boolean Replace an existing file. Default false.
path string Where to save the PNG. Default: the run's artifacts folder.

Output fields: bytes, height, path, sha256, url, width

# browser.waitFor

Wait until the open page reaches a state: an element matching a selector is present, visible or absent, the page text contains a string, and/or the URL matches a regular expression. Returns as soon as all given conditions hold; fails with a timeout otherwise.

  • side effect: read
  • default tier: 0
  • timeout: 120 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
selector string CSS selector to watch.
state string What the selector must be.
text string Text the page must contain.
timeoutSeconds number How long to wait. Default 10.
urlMatches string Regular expression the page URL must match.

Output fields: dialogs, elapsedMs, matched, title, url

# documents

# documents.csvRead

Parses a CSV file (RFC 4180 quoting, delimiter and header detected unless stated) and returns the columns and a bounded window of rows.

  • side effect: read
  • default tier: 0
  • timeout: 120 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
asObjects boolean Return each row as an object keyed by column name.
delimiter string One of , ; | or tab. Detected when absent.
header string Whether the first row is a header (default auto).
limit integer Rows returned (default 500).
offset integer Data rows to skip.
path string yes Absolute path, ~/ path, or path relative to the working directory.

Output fields: columns, delimiter, hasHeader, rowCount, rows, totalRows, truncated

# documents.csvWrite

Writes rows (arrays, or objects with columns) to a CSV file with RFC 4180 quoting. Refuses to replace an existing file unless overwrite is true (a backup is kept).

  • side effect: write
  • default tier: 1
  • timeout: 30 s
  • dry run: yes
Argument Type Required Description
columns array Header row; required order for object rows.
delimiter string
overwrite boolean
path string yes Absolute path, ~/ path, or path relative to the working directory.
rows array yes Arrays of cells, or objects keyed by column.

Output fields: bytes, path, rows

# documents.imageConvert

Converts one image (source → destination file) or a batch (paths → destination folder) to png, jpeg, heic, tiff, gif or bmp, optionally scaled down to a maximum dimension. Sources are never modified and existing files are not replaced unless overwrite is true.

  • side effect: write
  • default tier: 1
  • timeout: 600 s
  • dry run: yes
Argument Type Required Description
destination string yes Output file (single) or output folder (batch).
format string Required for a batch; inferred from the destination extension otherwise.
maxDimension integer Longest side in pixels; images are only ever scaled down.
overwrite boolean
paths array Images to convert as a batch.
quality number Lossy formats only (default 0.85).
source string Single image to convert.

Output fields: converted, count

# documents.imageInfo

Returns the format, pixel size, resolution, colour model, alpha, orientation and frame count of an image file.

  • side effect: read
  • default tier: 0
  • timeout: 30 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
path string yes Absolute path, ~/ path, or path relative to the working directory.

Output fields: bytes, format, height, width

# documents.jsonQuery

Reads a JSON file and returns the value at a path such as items[0].name, items[*].id or items[?price>10].name (operators == != > >= < <= ~=). An empty query returns the document outline.

  • side effect: read
  • default tier: 0
  • timeout: 30 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
limit integer Maximum values returned for wildcard/filter queries (default 200).
path string yes Absolute path, ~/ path, or path relative to the working directory.
query string Path expression; empty for an outline of the top level.

Output fields: count, found, result

# documents.pdfInfo

Returns the page count, page size, encryption state and document properties (title, author, dates) of a PDF.

  • side effect: read
  • default tier: 0
  • timeout: 30 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
path string yes Absolute path, ~/ path, or path relative to the working directory.

Output fields: bytes, encrypted, locked, pageCount

# documents.pdfText

Extracts the text layer of a PDF, page by page, for a page range. Scanned PDFs without a text layer return empty pages (hasText false).

  • side effect: read
  • default tier: 0
  • timeout: 180 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
firstPage integer 1-based (default 1).
lastPage integer Inclusive (default: last).
maxBytes integer Total text bound (default 200000).
path string yes Absolute path, ~/ path, or path relative to the working directory.

Output fields: hasText, pageCount, pages, truncated

# documents.renderPDF

Renders Markdown-like text into a paginated PDF: # headings, paragraphs with bold italic code, bullet and numbered lists, | tables |, ``` code blocks, --- rules, caption images and page numbers.

  • side effect: write
  • default tier: 1
  • timeout: 180 s
  • dry run: yes
Argument Type Required Description
author string
content string yes Markdown-like source.
destination string yes Path of the .pdf to create.
fontSize integer Body size in points (default 11).
overwrite boolean
pageSize string letter (default) or a4.
title string Document title (also printed as the first heading).

Output fields: bytes, pages, path

# documents.textStats

Counts lines, words, characters and bytes of a text file (or of given text) and lists its most frequent terms.

  • side effect: read
  • default tier: 0
  • timeout: 30 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
content string Text to analyse instead of a file.
minTermLength integer
path string Absolute path, ~/ path, or path relative to the working directory.
topTerms integer How many frequent terms (default 10).

Output fields: bytes, characters, lines, topTerms, words

# documents.xlsxRead

Reads the cell values of one sheet of an .xlsx workbook (shared strings, numbers, booleans, inline strings, cached formula results). Dates come back as serial numbers; legacy .xls and encrypted workbooks are unsupported.

  • side effect: read
  • default tier: 0
  • timeout: 120 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
limit integer Rows returned (default 500).
path string yes Absolute path, ~/ path, or path relative to the working directory.
sheet string Sheet name, or its 1-based position (default: first sheet).

Output fields: rowCount, rows, sheet, sheets, truncated, unsupported

# filesystem

# filesystem.archive

Compresses a file or a directory into a .zip archive. Refuses to replace an existing archive unless overwrite is true.

  • side effect: write
  • default tier: 1
  • timeout: 600 s
  • dry run: yes
Argument Type Required Description
destination string yes Path of the .zip to create.
keepParent boolean For a directory: store it as the top-level folder of the archive (default true).
overwrite boolean
source string yes Absolute path, ~/ path, or path relative to the working directory.

Output fields: bytes, destination, sha256

# filesystem.checksum

Computes the SHA-256 digest of a file.

  • side effect: read
  • default tier: 0
  • timeout: 300 s
  • idempotent
Argument Type Required Description
algorithm string
path string yes Absolute path, ~/ path, or path relative to the working directory.

Output fields: algorithm, bytes, digest, path

# filesystem.compare

Compares two files (identical or not) or two directory trees (entries added, removed and changed in destination relative to source).

  • side effect: read
  • default tier: 0
  • timeout: 300 s
  • idempotent
Argument Type Required Description
destination string yes Absolute path, ~/ path, or path relative to the working directory.
includeHidden boolean
limit integer Maximum paths per list (default 500).
source string yes Absolute path, ~/ path, or path relative to the working directory.

Output fields: identical, kind

# filesystem.copy

Copies a file or a directory tree to a destination path. Refuses to replace an existing destination unless overwrite is true (files only; a backup is kept).

  • side effect: write
  • default tier: 1
  • timeout: 300 s
  • dry run: yes
Argument Type Required Description
destination string yes Full path of the copy.
overwrite boolean
source string yes Absolute path, ~/ path, or path relative to the working directory.

Output fields: backupPath, destination, source

# filesystem.delete

Permanently deletes a file or directory. Irreversible: prefer filesystem.trash. A non-empty directory needs recursive: true.

  • side effect: destructive
  • default tier: 3
  • timeout: 300 s
  • dry run: yes
Argument Type Required Description
path string yes Absolute path, ~/ path, or path relative to the working directory.
recursive boolean Required to delete a non-empty directory.

Output fields: deleted, items, path

# filesystem.list

Lists the entries of a directory (name, type, size, modification date), optionally recursively to a bounded depth.

  • side effect: read
  • default tier: 0
  • timeout: 30 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
includeHidden boolean Include dot files (default false).
limit integer Maximum entries returned (default 500).
maxDepth integer Depth limit when recursive (default 3).
path string yes Absolute path, ~/ path, or path relative to the working directory.
recursive boolean Descend into subdirectories.

Output fields: count, entries, path, truncated

# filesystem.metadata

Returns type, size, dates, POSIX permissions, owner and content type of a file or directory.

  • side effect: read
  • default tier: 0
  • timeout: 30 s
  • idempotent
Argument Type Required Description
path string yes Absolute path, ~/ path, or path relative to the working directory.

Output fields: path, size, type

# filesystem.mkdir

Creates a directory (and missing parents). Succeeds when the directory already exists.

  • side effect: write
  • default tier: 1
  • timeout: 30 s
  • dry run: yes
  • idempotent
Argument Type Required Description
createParents boolean Default true.
path string yes Absolute path, ~/ path, or path relative to the working directory.

Output fields: created, path

# filesystem.move

Moves or renames a file or directory. Never replaces an existing destination: the call fails instead.

  • side effect: write
  • default tier: 1
  • timeout: 300 s
  • dry run: yes
Argument Type Required Description
destination string yes Full new path.
source string yes Absolute path, ~/ path, or path relative to the working directory.

Output fields: destination, source

# filesystem.read

Reads a file as UTF-8 text (bounded by maxBytes from an offset), or as base64 when encoding is base64.

  • side effect: read
  • default tier: 0
  • timeout: 30 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
encoding string utf8 (default) or base64 for binary content.
maxBytes integer Default 100000.
offset integer Byte offset to start from.
path string yes Absolute path, ~/ path, or path relative to the working directory.

Output fields: bytesRead, content, encoding, offset, path, totalBytes, truncated

# filesystem.search

Finds files under a directory by name glob and/or by content (substring or regular expression). Results and scanned bytes are bounded.

  • side effect: read
  • default tier: 0
  • timeout: 120 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
caseSensitive boolean Content matching is case-sensitive (default false).
content string Text to find inside files.
includeHidden boolean
maxDepth integer
maxFileBytes integer Files larger than this are not scanned for content (default 2 MB).
maxResults integer Default 100.
path string yes Absolute path, ~/ path, or path relative to the working directory.
pattern string Name glob such as *.pdf (matched on the file name).
regex boolean Treat content as a regular expression.

Output fields: count, filesScanned, matches, truncated

# filesystem.trash

Moves a file or directory to the Trash (recoverable) and returns where it now is.

  • side effect: write
  • default tier: 1
  • timeout: 30 s
  • dry run: yes
Argument Type Required Description
path string yes Absolute path, ~/ path, or path relative to the working directory.

Output fields: path, trashPath

# filesystem.unarchive

Extracts a .zip archive into a directory. Archives whose entries would land outside the destination (zip-slip) are refused, and existing files are never replaced.

  • side effect: write
  • default tier: 1
  • timeout: 600 s
  • dry run: yes
  • output is untrusted data
Argument Type Required Description
destination string yes Directory to extract into (created if missing).
source string yes Absolute path, ~/ path, or path relative to the working directory.

Output fields: count, destination, entries

# filesystem.waitForChange

Waits until a file or anything inside a directory changes, or until the timeout. Returns the changed paths; a timeout is a normal result with changed: false.

  • side effect: read
  • default tier: 0
  • timeout: 3060 s
  • idempotent
Argument Type Required Description
path string yes Absolute path, ~/ path, or path relative to the working directory.
timeoutSeconds number

Output fields: changed, events, timedOut

# filesystem.write

Creates a file, appends to it, or overwrites it when overwrite is true. An overwritten or appended file is first copied to the run's artifacts so the change can be undone.

  • side effect: write
  • default tier: 1
  • timeout: 30 s
  • dry run: yes
Argument Type Required Description
content string yes Text, or base64 when encoding is base64.
createParents boolean Create missing parent directories (default true).
encoding string
mode string create (default; fails if the file exists unless overwrite) or append.
overwrite boolean Required to replace an existing file.
path string yes Absolute path, ~/ path, or path relative to the working directory.

Output fields: backupPath, bytesWritten, created, path, sha256

# git

# git.branches

Lists local branches (and remote-tracking branches on request) with their tip, upstream and which one is checked out.

  • side effect: read
  • default tier: 0
  • timeout: 60 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
includeRemotes boolean
path string Repository directory (default: the run's working directory).

Output fields: branches, current

# git.commit

Stages the given paths and commits exactly those paths with a message. Hooks run; history is never amended or rewritten.

  • side effect: write
  • default tier: 1
  • timeout: 300 s
  • dry run: yes
  • output is untrusted data
Argument Type Required Description
message string yes
path string Repository directory (default: the run's working directory).
paths array yes Files or folders to commit.

Output fields: branch, commit, summary

# git.createPatch

Writes the unstaged, staged or range diff of a repository as a .patch file in the run's artifacts (untracked files are not included). The repository is not modified.

  • side effect: read
  • default tier: 0
  • timeout: 120 s
  • idempotent
Argument Type Required Description
name string File name without extension.
path string Repository directory (default: the run's working directory).
paths array
range string Revision or range such as main..feature.
staged boolean

Output fields: bytes, empty, patchPath

# git.diff

Shows the unstaged diff, the staged diff, or the diff of a revision range (a..b), optionally limited to paths. Output is bounded.

  • side effect: read
  • default tier: 0
  • timeout: 120 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
contextLines integer
maxBytes integer Default 100000.
path string Repository directory (default: the run's working directory).
paths array Limit to these paths.
range string Revision or range such as main..feature.
staged boolean Diff of the index against HEAD.
stat boolean Only the per-file summary.

Output fields: diff, empty, truncated

# git.log

Lists recent commits (hash, author, date, subject) of a branch or revision range, optionally limited to paths.

  • side effect: read
  • default tier: 0
  • timeout: 60 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
limit integer Default 20.
path string Repository directory (default: the run's working directory).
paths array
ref string Branch, tag, commit or range.

Output fields: commits, count

# git.push

Pushes one branch to a configured remote. This publishes commits outside the Mac; force replaces remote history and is high-risk.

  • side effect: external
  • default tier: 2
  • timeout: 600 s
  • dry run: yes
  • output is untrusted data
Argument Type Required Description
branch string Branch to push (default: the current branch).
force boolean Replace the remote branch.
path string Repository directory (default: the run's working directory).
remote string Remote name (default origin).
setUpstream boolean
timeoutSeconds number Seconds before the call is stopped.

Output fields: branch, forced, output, remote

# git.status

Reports the branch, upstream, ahead/behind counts and the staged, unstaged, untracked and conflicted files of a repository.

  • side effect: read
  • default tier: 0
  • timeout: 60 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
path string Repository directory (default: the run's working directory).

Output fields: clean, staged, unstaged, untracked

# http

# http.request

Sends one HTTP request (HTTPS only, plain HTTP allowed for loopback) to a declared host and returns status, headers and a bounded body. Redirects to another host are reported, not followed. Secrets go in secretHeaders by reference and are never echoed.

  • side effect: external
  • default tier: 2
  • timeout: 300 s
  • output is untrusted data
Argument Type Required Description
body string Request body text.
followRedirects boolean Follow redirects that stay on the same host (default true).
headers object
maxBytes integer Response body bound (default 200000).
method string Default GET.
secretHeaders object Header name → secret reference name. The header value is the secret (prefix it with secretPrefix if needed).
secretPrefix string Text put before each secret value, for example "Bearer ".
timeoutSeconds number Seconds before the call is stopped.
url string yes Absolute URL.

Output fields: body, bodyEncoding, headers, redirect, status, truncated, url

# notifications

# notifications.post

Shows a local notification from ORIX OS Automation. With an approvalID it carries Approve / Deny / Open buttons; the answer goes to the app, not to the agent.

  • side effect: write
  • default tier: 1
  • timeout: 15 s
  • dry run: yes
  • macOS permission: notifications
Argument Type Required Description
approvalID string Approval request the notification asks about.
body string yes Notification text.
runID string Run the notification belongs to.
sound boolean Play the default sound (default true).
subtitle string
title string yes Notification title.

Output fields: id, posted

# python

# python.envInfo

Describes ORIX's managed Python environment: whether it exists yet, interpreter path and version, and the installed packages.

  • side effect: read
  • default tier: 0
  • timeout: 60 s
  • idempotent

Output fields: exists, interpreter, packages, root, version

# python.run

Runs Python code (or a script file) in ORIX's own virtual environment, inside a sandbox limited to the run's granted folders. Files it creates are returned as artifacts. Packages can be installed first, exact pins only (name==1.2.3).

  • side effect: external
  • default tier: 2
  • timeout: 1800 s
  • output is untrusted data
Argument Type Required Description
args array sys.argv[1:].
code string Python source to run.
cwd string Working directory (default: a fresh folder in the run's artifacts).
maxBytes integer
path string Script file to run instead of code.
requirements array Packages to install first, each pinned as name==version.
stdin string
timeoutSeconds number Seconds before the call is stopped.

Output fields: durationMs, exitCode, stderr, stdout, truncated

# screen

# screen.capture

Takes a PNG screenshot of one display, of an application's frontmost window, or of a rectangular region. Windows of password managers are left out, and nothing is captured while secure keyboard input is active.

  • side effect: write
  • default tier: 1
  • timeout: 30 s
  • macOS permission: screenRecording
Argument Type Required Description
bundleID string Application whose frontmost window is captured, for scope window.
displayIndex integer Display to capture for scope display (0 is the main display).
overwrite boolean Replace an existing file at path (default false).
path string Where to write the PNG (default: the run's artifacts directory).
region object Rectangle in global screen points (origin top-left of the main display), for scope region.
scope string yes What to capture.

Output fields: path, pixelHeight, pixelWidth, scale, scope

# screen.compare

Compares two image files of the same pixel size and returns the ratio of changed pixels and the bounding box of the difference; can write an annotated PNG showing what changed.

  • side effect: write
  • default tier: 1
  • timeout: 120 s
  • idempotent
Argument Type Required Description
after string yes Second image file.
before string yes First image file.
diffPath string Optional PNG to write: the second image with changed pixels tinted red and the difference outlined.
overwrite boolean Replace an existing file at diffPath (default false).
tolerance integer Per-channel difference (0–255) below which a pixel counts as unchanged (default 8).

Output fields: changedPixels, changedRatio, height, identical, totalPixels, width

# screen.ocr

Recognises text in an image file (PNG, JPEG, TIFF, HEIC …) on this Mac with Vision and returns text blocks with confidence and bounding boxes (top-left origin, normalised and in pixels).

  • side effect: read
  • default tier: 0
  • timeout: 120 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
fast boolean Use the fast recogniser instead of the accurate one (default false).
languages array Preferred recognition languages, for example ["en-US", "fr-FR"] (default: automatic).
maxBlocks integer Maximum text blocks returned (default 400).
path string yes Image file.

Output fields: blocks, imageHeight, imageWidth, text

# script

# script.javascript

Runs JavaScript in the system JavaScriptCore shell (jsc) as a separate sandboxed process: print(), readFile(), arguments are available; there is no DOM, no Node API and no network.

  • side effect: external
  • default tier: 2
  • timeout: 1800 s
  • output is untrusted data
Argument Type Required Description
args array
cwd string Working directory (default: a fresh folder in the run's artifacts).
maxBytes integer
script string yes JavaScript source.
timeoutSeconds number Seconds before the call is stopped.

Output fields: durationMs, exitCode, stderr, stdout, truncated

# script.swift

Runs a Swift script with the system toolchain inside a sandbox limited to the run's granted folders (no network unless a host is granted). Needs the Xcode command line tools.

  • side effect: external
  • default tier: 2
  • timeout: 1800 s
  • output is untrusted data
Argument Type Required Description
args array
cwd string Working directory (default: a fresh folder in the run's artifacts).
maxBytes integer
script string yes Swift source.
timeoutSeconds number Seconds before the call is stopped.

Output fields: durationMs, exitCode, stderr, stdout, truncated

# shell

# shell.run

Runs one executable with an explicit argument array (no shell, no interpolation), confined to the folders granted to the run. Refuses sudo/su/doas and interpreters given inline code; a non-zero exit code is returned, not raised.

  • side effect: external
  • default tier: 2
  • timeout: 1800 s
  • output is untrusted data
Argument Type Required Description
args array Arguments, passed verbatim as separate argv elements.
cwd string Working directory (default: the run's working directory).
env object Extra environment variables.
executable string yes Program name (resolved through a fixed system PATH) or absolute path.
maxBytes integer Output bound per stream (default 100000).
stdin string Text written to the program's standard input.
timeoutSeconds number Seconds before the call is stopped.

Output fields: durationMs, exitCode, stderr, stdout, truncated

# shell.script

Runs bash script text inside a Seatbelt sandbox: it can only write to the folders granted to the run and its artifacts, and has no network unless a host is granted. Privilege escalation is refused.

  • side effect: external
  • default tier: 2
  • timeout: 1800 s
  • output is untrusted data
Argument Type Required Description
args array Positional parameters ($1, $2 …).
cwd string Working directory (default: the run's working directory).
env object
maxBytes integer
script string yes Bash source.
timeoutSeconds number Seconds before the call is stopped.

Output fields: durationMs, exitCode, stderr, stdout, truncated

# skill

# skills.install

Install a draft produced by skills.propose as a versioned local tool. The user reviews its source, permissions, analysis and test results and must approve. After installation the tool skill. is available.

  • side effect: external
  • default tier: 2
  • timeout: 30 s
Argument Type Required Description
draftID string yes

# skills.list

List installed skills and pending drafts with their versions and permissions.

  • side effect: read
  • default tier: 0
  • timeout: 30 s
  • idempotent

# skills.propose

Propose a new reusable tool when no existing tool fits. Give a manifest (name, summary, runtime python or bash, input/output schemas, the exact file and network permissions it needs), the source, and tests with fixture files. The source reads its input as JSON on stdin and prints one JSON object on stdout. The package is analysed and its tests are run in a sandbox with no network. Nothing is installed: use skills.install afterwards, which asks the user.

  • side effect: external
  • default tier: 2
  • timeout: 300 s
Argument Type Required Description
fileRead array
fileWrite array
inputSchema object yes JSON Schema of the input object
name string yes camelCase name; the tool becomes skill.
network array
outputSchema object JSON Schema of the output object
runtime string yes
source string yes Complete source of the entry file
summary string yes What the tool does, for a model choosing tools
tests array yes
title string yes Human-readable name
version string major.minor.patch

# system

# clipboard.read

Reads the text and the file paths currently on the clipboard. Other kinds of content are only named, and entries marked as concealed by a password manager are withheld.

  • side effect: read
  • default tier: 0
  • timeout: 10 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
maxBytes integer Maximum text size returned (default 100000).

Output fields: changeCount, concealed, fileURLs, text, types

# clipboard.write

Replaces the clipboard with text, or with a list of files (as if copied in Finder).

  • side effect: write
  • default tier: 1
  • timeout: 10 s
  • dry run: yes
  • idempotent
Argument Type Required Description
content string Text to place on the clipboard.
paths array Files to place on the clipboard instead of text.

Output fields: changeCount, kind, written

# system.apps

Lists running applications with name, bundle identifier, process id and whether each is active or hidden.

  • side effect: read
  • default tier: 0
  • timeout: 10 s
  • idempotent
Argument Type Required Description
includeBackground boolean Also list background agents and menu-bar-only apps (default false).

Output fields: applications

# system.diskUsage

Lists mounted volumes with total and available capacity.

  • side effect: read
  • default tier: 0
  • timeout: 30 s
  • idempotent
Argument Type Required Description
includeHidden boolean Include system volumes hidden from the Finder.

Output fields: volumes

# system.frontmost

Reports the frontmost application and, when Accessibility or Screen Recording access allows it, the title of its focused window. Says which source was used and why a title is missing.

  • side effect: read
  • default tier: 0
  • timeout: 10 s
  • idempotent
  • output is untrusted data

Output fields: application, titleSource, windowTitle

# system.info

Reports the macOS version, Mac model, processor, core counts, memory and uptime of this Mac.

  • side effect: read
  • default tier: 0
  • timeout: 30 s
  • idempotent

Output fields: cores, cpu, memoryBytes, model, osVersion, uptimeSeconds

# system.launchApp

Launches an application by bundle identifier or path (or brings it forward if it is running) and waits until it reports that it finished launching.

  • side effect: write
  • default tier: 2
  • timeout: 90 s
  • dry run: yes
  • idempotent
Argument Type Required Description
activate boolean Bring the application to the front (default true).
bundleID string Application bundle identifier, for example com.apple.finder.
path string Path of the application bundle, as an alternative to bundleID.
timeoutSeconds number How long to wait for the launch to finish (default 30).

Output fields: alreadyRunning, bundleID, finishedLaunching, pid

# system.networkState

Reports whether the Mac currently has a usable network path and through which interface types (Wi-Fi, wired, cellular), without contacting any host.

  • side effect: read
  • default tier: 0
  • timeout: 30 s
  • idempotent

Output fields: interfaces, online, status

# system.powerState

Reports whether the Mac runs on AC power or battery, and the charge and charging state of each battery (a desktop Mac has none).

  • side effect: read
  • default tier: 0
  • timeout: 30 s
  • idempotent

Output fields: batteries, hasBattery, onACPower, source

# system.processes

Lists the processes using the most CPU or memory (pid, parent, CPU %, memory %, resident size, user, name).

  • side effect: read
  • default tier: 0
  • timeout: 30 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
limit integer Default 15.
sortBy string cpu (default) or memory.

Output fields: processes, total

# system.quitApp

Asks an application to quit the normal way (it may ask the user to save) and reports whether it did. Never force-quits.

  • side effect: write
  • default tier: 2
  • timeout: 60 s
  • dry run: yes
  • idempotent
Argument Type Required Description
bundleID string yes Application bundle identifier, for example com.apple.finder.
timeoutSeconds number How long to wait for the application to quit (default 10).

Output fields: bundleID, refused, terminated, wasRunning

# system.windows

Lists on-screen windows front to back: owner application, bounds, layer and display. Window titles are included only when Screen Recording access is enabled; the output says whether they are.

  • side effect: read
  • default tier: 0
  • timeout: 10 s
  • idempotent
  • output is untrusted data
Argument Type Required Description
bundleID string Only windows of this application.
includeAllLayers boolean Include menu bar, Dock and overlay layers (default false: normal windows only).
maxWindows integer Maximum windows returned (default 200).

Output fields: displays, titlesAvailable, windows

Files main
Menu

Theme