Oko
Oko/Docs

Command reference

oko api call

Sends one structured native API request to the running Oko service and prints its actual result.

Invocation#

Command
oko api call --file PATH [--socket PATH]

Inputs and options#

  • PATH contains a JSON request with version, operation.domain and operation.request.action. Optional location names an owned register; operations that do not accept a location refuse it.
  • Read-only example: {"version":1,"operation":{"domain":"autonomy","request":{"action":"policy"}}}. The API uses typed fields, not CLI argument arrays.

Output and state effect#

  • The resident Rust operation uses the same ledger, register or provider operation as the CLI. Mutations change real state and require the same operator intent as their graphical action. A response carries ok, api_version and result; failures name the operation and actual cause.
  • Task record requests contain a mutation object with its action and typed fields. The Close sheet supplies the reason and the exact task identity the operator typed. Calling the diagnostic command is not permission for an agent to close the operator's task.
  • The tasks request {"action":"judge"} reads saved judge health without calling a model. Adding "probe":true explicitly asks the selected service and persists that observation in the shared database and the local gate copy. A completed probe whose model refused returns answering:false in its result; a persistence failure is a failed API operation. Desktop's Model access screen uses these operations for saved status and Probe judge.
  • The tasks request {"action":"judge_provider","operation":{"action":"show"}} reads the credential-free model choice. Operation set takes origin, model and key; unset removes the declaration and returns to Brama. These use the CLI's validation and owner-only storage without a database or model call. Desktop's Judge provider form sends the key directly over the native socket, never as a CLI argument, and confirms set/unset. Responses never include the stored key.
  • The sessions start action takes runtime, executable, arguments, directory, terminal_type, columns and rows. The directory and terminal type must be nonempty; dimensions must be positive terminal sizes. It uses the broker's Brama routing and sandbox path and returns the owned session record, including attachSocketPath. OkoKit exposes it as OkoSessions.start without launching a CLI process.
  • The sessions resize action takes id, columns and rows for a session this broker owns. OkoSessions.resize sends the same request. Invalid dimensions, an unknown session or a failed terminal resize remain errors; a failed resize does not report success or send a redraw signal.
  • After the kernel accepts a new terminal size, a failed window-change notification reports that the size changed but its process-group signal failed, including the session, group and actual operating-system cause. Repaint uses the same group notification and refuses its failure without substituting a signal to the group leader. Accepted signaling is not proof of a visible redraw.
  • The agent request {"action":"harnesses"} answers the harness catalogue read against this machine, the same rows as `oko agent harnesses`, without starting any harness. OkoKit exposes it as OkoHarnesses.list; Desktop's Model access → Coding harnesses section shows it.

Refusals and safe exits#

  • Missing or unreadable request files, invalid JSON, unknown fields or variants, mismatched protocol versions, unavailable dependencies and refused product operations exit unsuccessfully. No fallback CLI process or substitute result is used.

CLI reference#