Reference

Socket API

This page describes the local socket of a Tiza instance. It covers the connection, the requests, the methods, the error codes and the commands. The MCP tools send the same requests.

Connect

Each instance listens on a Unix socket on your computer, unless you start it with --no-socket. The socket never listens on TCP. See Privacy and network.

Tiza selects the socket in this order:

1. --socket PATH.
2. $TIZA_SOCKET.
3. SESSION.sock in the runtime folder. SESSION is --session NAME, else $TIZA_SESSION, else default.

• For the runtime folder, the permissions and what --socket changes on disk, see The runtime folder.
• An empty variable is the same as a variable that is not set.
• An empty --session is not the same as no session. It gives the socket .sock.
• In a session name, each character that is not an ASCII letter, a digit, - or _ becomes _.
• Every command that uses the socket takes --socket and --session: the TUI, tiza mcp, tiza api, tiza scene, tiza render, tiza next, tiza prev and tiza goto.
• To run several instances, give each one its own session.

When the socket cannot start, the instance starts without a socket. The status bar shows one of these messages:

• After local API disabled: comes a message of Tiza or an error of the system.
• The messages of Tiza are in Messages.

Requests and responses

Send one JSON object on one line. The instance answers with one JSON object on one line.

The response has id and one of these fields:

• result: the result of the method.
• error: an object with code and message. Use the code in your client. The message is for a person.

For example, when TMPDIR is set and XDG_RUNTIME_DIR, TIZA_SOCKET and TIZA_SESSION are not set:

printf '%s\n' '{"id":1,"method":"annotation.add","params":{"type":"note","line":4,"text":"hello"}}' | nc -U "$TMPDIR/tiza/default.sock"

{"id":1,"result":{"hidden":"it appears at step 1","id":"a17","revision":4,"shown_step":0,"step":1,"visible":false}}

• A connection can send several requests. The instance answers them in the order that they come.
• In supervised mode, a request that waits also stops the requests after it on the same connection, for up to 60 s.
• Thus use one connection for each request, as tiza api does.
• The instance skips an empty line.
• A line that is not JSON gets the error invalid_json. Its id is null when the instance cannot read it.
• A line without id, or without method as a string, also gets the error invalid_json.
• A request without params is the same as "params": null.
• These methods refuse null with invalid parameters:: annotation.add, annotation.update, annotation.delete, scene.clear, scene.put, scene.patch, move.add, move.delete, step.set, step.goto, pointer.set and check.
• For scene.clear, scene.patch and check, send {} when you have no parameter to give. pointer.set with {} fails, because it needs a place.
• style.set, follow.set and supervise.set also refuse null, because they need a field.
• The other methods take null as no parameters. Thus focus.set clears the focus and theme.set changes the theme between dark and light.
• A result can get new fields in a new version. Ignore a field that you do not know.
• status and api.schema give protocol, the version of the protocol. It is 1.
• Each command that sends a request waits 75 s for a response. This includes tiza mcp, tiza next, tiza prev, tiza goto and tiza render without a file.
• A request in supervised mode waits at most 60 s.

Methods

api.methods gives each method with its description. The MCP tool column names every tool that sends the method.

Instance

Read

• width of check is from 20 to 400. The default is the width of the config file, else 100.

Annotations

Document

Moves

Steps

Focus and pointer

Theme and follow mode

Supervised mode methods

The arguments of the MCP tools are in Arguments. The socket uses the same names, with the differences in Differences from the MCP tools. The schema gives the full contract of each method: its parameters and all the fields of its result.

Differences from the MCP tools

• annotation.add takes type, one of the seven annotation types, and the fields of that type.
• annotation.add takes file, the file that the annotation belongs to, as a code.link names it. Without file, or with null, the annotation goes to the file on screen at its step.
• An arrow takes heads, an object {start, end}, in place of head_start and head_end. A missing end gets its default.
• An anchor also takes end, the grapheme after the span, with line and col. Without end, a span goes to the end of the line.
• Tiza uses end only when the anchor has no find. The from and to of an arrow ignore end.
• annotation.update takes the new place in move: {"id": "a1", "move": {"at": {"find": "s: String"}}}. move takes at, from, to, from_line and to_line.
• annotation.update takes shape, which replaces the whole shape of the annotation.
• annotation.update takes heads with one end only. The other end stays.
• annotation.add and annotation.update take effect, the experimental enter effect: draw, fade or null. In annotation.update, an absent effect keeps the effect, and null removes it.
• draw on an annotation without a stroke fails with invalid_argument. annotation.update checks it when the request has effect, shape or emphasis. Other updates keep the effect, also on an annotation from a file.
• theme.set without theme changes between dark and light, as Agents and themes tells. The MCP tool set_theme needs theme.

scene.clear

• Send {} to clear every annotation, or {"step": N} to clear one step. N is a whole number from 0 to 4294967295.
• Tiza refuses any other parameters with invalid_argument, and changes nothing.
• The presenter can undo a scene.clear with u.

scene.put and scene.patch

• scene.put takes document, a .tiza object with its code embedded. The instance cannot read a file reference that you send.
• Tiza refuses a document with a newer schema with unsupported_schema, and nothing changes.
• The message is the same as when a file opens, for example .tiza document with schema 99: this version of Tiza reads schema 1 at most.
• Tiza migrates a document with an older schema, as it does for a file. When Tiza saves the document, it writes the current schema.
• The presenter can undo a scene.put with u. The undo also gives back the step.
• For the save rules, see Agents and saving.
• scene.patch takes these fields: step, theme, padding, title, numbers, margin, styles, annotations, steps and loop.
• A step after the last step becomes the last step.
• padding, title and margin take null, which gives back the default.
• styles merges the styles by name. A style with the same name replaces the old one.
• steps replaces the whole list of named steps. [] clears it.
• annotations merges full annotations by id. A new id adds an annotation, and the same id replaces one. {"id": "a1", "deleted": true} deletes one.
• deleted for an id that the document does not have fails with invalid_argument.
• A replaced annotation keeps its step without step, and its file without file. file: null is the main file.
• A new id gets the defaults of annotation.add. file: null is then the file on screen at its step.

For example:

tiza scene patch '{"step":2,"theme":"light","annotations":[{"id":"a1","deleted":true}]}'

Tiza refuses a scene put in these saving cases. The error code is invalid_argument. The document and the file on disk do not change.

ERROR is the read error of Tiza. It ends with the error text of the system.

Keys that Tiza does not know

These methods refuse a key that they do not know: annotation.update, scene.clear, scene.get, scene.patch, pointer.set and supervise.set. The move object of annotation.update also refuses one. The error is invalid_argument, and its message names the keys that the method knows. scene.get knows no key.

A position also refuses a key that it does not know, in every method. These are the positions:

• the at, from and to of annotation.add, annotation.update and move.add;
• the span and the arrow ends of the annotations of scene.put and scene.patch;
• the from and to of a select move of scene.put;
• the rebind entries.

For example, "at": {"line": 3, "start": 4} fails, because a position calls its first grapheme col. A span calls it start.

When a method refuses a key that it does not know, the message names a known key that is near. That key is one or two letters from it, or it starts the key (col for column). For start, col and text in a position or a span, the message names the field of that position:

move.add and scene.put refuse a key of a move that the action of the move does not know. The message names the first of these keys in alphabetical order, and the keys of the action. When that key is one or two letters from a key of the action, the message names that key. When that key is a key of another action, the message names that action. In scene.put, the message also names the move by its number in moves. The keys that move.list adds to a move (index, summary, stale and stale_reason) are not refused. Thus you can send an entry of move.list to move.add again.

A file with a key that this version does not know opens, and tiza check gives a warning (see Moves from a newer version).

Results

• message tells what the method did, in words.
• label is the step label: the text of the status bar for the step, for example step 3/7 · Shared borrow.
• pending of supervise.status is a list of {id, method, summary, age_ms}. In status, pending is a number, and pending of its follow field is true or false.
• shown of pointer.set is false while the presenter has the command line open. The pointer shows when the command line closes.
• hash of follow.status is the sha256 of the followed file as Tiza last read it, in lowercase hex, as shasum -a 256 FILE prints it. It is the hash of the whole file, also when the code is a range of it. It is null when Tiza could not read the file, for example when the file is removed. reads counts the reads of the file, also the reads that load nothing. A save of the same bytes does not change hash: then reads increases. See Agents and follow mode.
• The fields of the check report are in Check report.

Invisible characters in code.get

text gives the real characters of the code. Some of them do not show on the screen as they are. invisible is a list of these characters, in the order of the code. Each item is {line, col, code_point, name}, for example {"line": 3, "col": 5, "code_point": "U+200B", "name": "zero width space"}.

• col is the grapheme, counted from 0, as the col of an anchor. A joiner in the grapheme of a letter has the column of that letter. For example, in ad U+200D min, the joiner has col 1.
• The list has each character that the screen shows as ⬚, and each control character other than the tab. See Control and invisible characters.
• A character that has a function on the screen is not in the list, for example the joiner of an emoji sequence. A tab is not in the list.
• The list is empty when the code has none of these characters.
• A find for a text with such a character must hold the real character, for example "ad\u200bmin" in JSON. To point at the character itself, use line and col. See A find inside a character.

A find inside a character

A character (a grapheme) can be more than one code point, for example d with a joiner, e with a combining accent, or an emoji sequence.

• When a column comes from a find, that edge of the text must be on the edge of a grapheme:

  • a span, the at of a highlight or a mark, uses the two edges;
  • an arrow end, from or to, and the from of a select use the start of the text;
  • the to of a select uses the end of the text.

• This applies in annotation.add, annotation.update with shape or move, move.add, scene.put, and a rebind entry of a span or an arrow end.

• When that edge is inside a grapheme, the method fails with invalid_argument. For example, a joiner alone in ad U+200D min on line 1 gives:

  text "\u{200d}" starts inside the character "d\u{200d}" at line 1, col 1: put the whole character in the find, or use line and col

• Put the whole character in the find, for example "d\u200d" in JSON, or use line and col.

• When only the line counts, this is not an error: a find_start or find_end marker, the at of a note (in annotation.update with move, and in a rebind), the target of a code.patch, and pointer.set.

• annotation.update refuses a new shape when a rebind of the annotation would not work with it. An example is a note whose rebind has a joiner alone, which cannot become a highlight.

• occurrence counts every match, also a match inside a grapheme.

Fields of status

• A field that does not apply is not in the result, except file, pointer and save_error, which are null.
• loop, supervised and effect are not in the result when they are false. pending and stale_moves are not in the result when they are 0.
• by of pointer is presenter or agent. It tells who moved the pointer last.
• revision grows when something changes, by 1 or more. A request that changes nothing keeps it.
• A change is a change of the document or of what the instance shows. Examples are the step, the focus, the theme and supervised mode.
• One request can add more than 1. For example, theme.set, scene.put and scene.patch add 2.
• scene.patch with {}, and annotation.update with only id, change nothing. They keep revision.
• pointer.set, pointer.clear and follow.set do not change revision.
• In follow mode, a reload or a relink changes the document. Thus it changes revision.
• Compare revision to find a change. Do not count on steps of 1.

Error codes

• After busy, send the check again.
• After internal, the instance keeps running. It undoes the whole request: the document, the screen and the undo entry go back to what they were.
• Do not try again in a loop after rejected or internal. Tell the presenter.

Messages

These messages come from the socket itself. The other messages come from each method.

• invalid request: and invalid parameters: end with the error of the JSON parser. check: could not start the check: ends with the error of the system.
• METHOD is request when the method does not exist.
• The internal message adds , and nothing of it was kept for a method that changes something.
• It ends with (details in PATH) when Tiza could write panics.log. PATH is the path of that file.

Command line

These commands use the socket of the live instance.

For example:

tiza scene status
tiza api annotation.add '{"type":"note","line":4,"text":"hello"}'
tiza api move.add '{"at_step":2,"action":"code.patch","op":"insert","after":"let b = 2;","content":"    let c = 3;","typing":"line"}'
tiza scene put other.tiza
tiza render --out shot.png

• PARAMS is a JSON object. Without it, tiza api sends {}.
• tiza scene put reads the code of a file reference and sends it embedded. It also sends the linked files.
• tiza scene put refuses a file that is not a document. With --as-code, it shows the file as code.
• tiza scene put takes the step of the output of tiza scene get.
• tiza scene patch takes @FILE to read the JSON from a file.
• tiza scene text without --width uses the width of the code area of the screen. The add tools use this width for visible.
• tiza render without a file exports the live instance. See The live instance.
• The other commands print the result as indented JSON.

tiza check FILE --json does not use the socket. It checks a .tiza file on disk and prints the report as JSON. It exits with 1 when the report has errors. See Check report.

Errors on the command line

A command prints an error on stderr after tiza: and exits with 1.

• For a file that Tiza cannot read, could not read FILE comes first, also with --as-code.
• These messages end with : and an error: no Tiza instance is listening, could not read, could not open, the two messages about a document that is not valid, and the three messages about JSON. The error comes from the system, or from the parser.
• The message no Tiza instance is listening comes for each of these cases:
  • The command cannot connect to the socket.
  • The command cannot write the request.
  • The reply is not JSON.

Standard input

- reads the standard input in these commands:

• tiza api METHOD - reads PARAMS.
• tiza scene put - reads the document.
• tiza scene patch - reads the JSON.
• tiza render - reads a document or code. For code, --lang gives the language. See Exports.
• tiza check - reads a document.
• tiza - reads the code that the TUI shows. tiza with a pipe on its standard input does the same.

For example:

cat demo.tiza | tiza render - --out -
pbpaste | tiza render - --lang rs --out shot.png
tiza render - --out shot.png < demo.tiza

Schema

The contract of the socket is a JSON Schema. It has the parameters and the result of each method, and the request and response lines.

• tiza schema api prints it. --out PATH writes it to a file.
• api.schema gives the same schema from the live instance. A client can check what it sends before it sends it.
• The repository holds it in schema/api.schema.json. A test makes sure that this file is equal to the output of tiza schema api.
• tiza schema document prints the schema of the .tiza document, schema/tiza.schema.json.

Supervised mode

In supervised mode, a request that changes something waits until the presenter accepts it or rejects it. See Supervised mode.

These methods wait:

• Annotations: annotation.add, annotation.update, annotation.delete, scene.clear, style.set.

• Document: scene.put, scene.patch.

• Moves: move.add, move.delete.

• Steps: step.set, step.next, step.prev, step.goto.

• Focus and pointer: focus.set, pointer.set, pointer.clear.

• Theme and follow mode: theme.set, follow.set.

• Supervised mode: supervise.set with "enabled": false. Its summary in the review is turn supervised mode off.

• The other methods never wait. They are the methods that read, supervise.set with "enabled": true and supervise.status.

• An accepted request gives its usual result. A rejected request fails with rejected.

• When supervised mode goes off, Tiza rejects each change that waits. A waiting supervise.set with "enabled": false gets its usual result, not rejected.

• Some requests get their error at once and do not wait:

  • A method that does not exist. It gets invalid_argument with unknown method (`api.methods` lists them).
  • A scene.clear with wrong parameters.
  • A scene.put with a newer schema.
  • A supervise.set with wrong parameters, for example an unknown key or no enabled.

• Other wrong parameters still wait. They fail when the presenter accepts the change.

How it works

• The design of the protocol comes from herdr: one request on each line, and method names with dots.
• Each connection has its own thread. The thread sends each request to the TUI, and the TUI is the only part that changes the document.
• check runs on a copy of the document in its own thread. The screen and the other requests do not wait for it. At most one check runs and one waits.
• The MCP server is a client of the socket. Most tools send one method. list_annotations and export_image send two. status adds the bridge object of the server.