Developers
CLI reference
The rooqi command — status, list, read, run and pdf — with input formats and exit codes.
rooqi status | list | read DOCUMENT_UUID | run < commands.json | pdf < pdf-commands.json | mcpEvery command writes one JSON response envelope per line to standard output.
Commands
rooqi status
Checks the connection. Exit code 0 when code is ready, otherwise 1.
rooqi list
Requests read access, waits for approval (up to 120 seconds), then lists approved documents.
rooqi read DOCUMENT_UUID
Requests read access, waits for approval, then prints the saved text of one document. A malformed UUID exits with 64.
rooqi run
Reads a JSON array of 1–16 request objects from standard input, requests create/append access, waits for approval, then executes them in order. Allowed methods: createNote, appendText. Execution stops at the first response that isn’t ready.
rooqi pdf
Same as run, but requests PDF annotation access. Allowed methods: listApprovedDocuments, listPDFTargets, readPDFPage, annotatePDF, queryPDFOperation.
rooqi mcp
Starts the MCP server on stdio. See the MCP tool reference.
Request objects
Each object in a run or pdf batch is a protocol request:
| Field | Required for | Notes |
|---|---|---|
version | all | Always 1 |
requestID | all | UUID, unique per request |
method | all | See above |
mutation | createNote, appendText | {operationID, documentID, title?, text?, expectedVersion?, provider, model, promptVersion} |
documentID | listPDFTargets, queryPDFOperation | UUID |
pdfQuery | readPDFPage | {documentID, surfaceID, pageIndex, rect} |
pdfAnnotation | annotatePDF | Same fields as the MCP rooqi_annotate_pdf input |
operationID | queryPDFOperation | UUID |
For createNote, mutation has title (1–200 characters) and no text or expectedVersion. For appendText, it has text (1–6,000 bytes) and expectedVersion, and no title. Unknown fields are rejected.
Exit codes
| Code | Meaning |
|---|---|
0 | Every response was ready |
1 | A response wasn’t ready (including denied or timed-out approval) |
64 | Usage error or invalid input |
Example
cat > commands.json <<'JSON'
[
{
"version": 1,
"requestID": "8E0B7C1E-7B53-4C39-9A55-2B9F2C1E0A01",
"method": "createNote",
"mutation": {
"operationID": "5C3D8F0A-2E6B-4F1C-8D7A-9B0E1F2A3B4C",
"documentID": "0F1E2D3C-4B5A-4968-8776-655443322110",
"title": "Reading notes",
"provider": "my-script",
"model": "none",
"promptVersion": "1"
}
}
]
JSON
rooqi run < commands.jsonApprove the window in RooQi when it appears. Keep commands.json: if the result is uncertain, run the same file again — the same operationID won’t write twice.