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,
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