Reference

Command line

This page lists the shell commands, the arguments and the flags of tiza. It also explains how Tiza finds the language of the code.

Open code

Give tiza a file, or send code to its standard input. For example:

tiza src/main.rs                            # open a file
tiza src/main.rs:12-48                      # open lines 12 to 48, with their line numbers
tiza src/main.rs --follow                   # reload when you save the file in the editor
pbpaste | tiza --lang rs                    # open code from the clipboard (macOS)
tiza examples/ownership.rs.tiza --present   # open a document in presentation mode

FILE is one of these:

• A range can also be A..B.
• Without FILE, Tiza reads standard input when it is not a terminal.
• Text on standard input that starts with { and contains "schema" is a document. Other text is code.
• With a range, Tiza saves to FILE.A-B.tiza. When that file exists, Tiza opens it, as it opens FILE.tiza without a range, and says so on the status bar. Another range, such as A-C, is another document. See Where the document goes.
• A .tiza path with a range opens the document and ignores the range.
• When Tiza clamps a range, it saves under the clamped lines. For example, tiza three.txt:2..9 on a file of three lines saves to three.txt.2-3.tiza.
• When a range goes past the end of the file, Tiza shows the lines that exist.

Commands

• The live instance is the running TUI that agents and these commands talk to. See Global flags.
• For each flag of tiza render, see Options of tiza render.
• tiza check is in Check before you record.
• tiza config is in Config file.
• tiza mcp is in Set up an agent. The tools are in MCP tools.
• tiza scene and tiza api are in Socket API.
• tiza next, tiza prev and tiza goto are in Go to a named step.

Options of the commands

• N in --width N is from 20 to 400.
• JSON in tiza scene patch is the text of the JSON, - for standard input or @PATH for a file.
• PARAMS in tiza api is the text of the JSON, or - for standard input. Without PARAMS, Tiza sends {}.
• FILE in tiza scene put and tiza check can be - for standard input.
• tiza check also takes a source file that has a .tiza document next to it.

For example:

tiza check demo.tiza --json
tiza api annotation.add '{"type":"note","line":4,"text":"hello"}'
tiza scene patch @change.json
tiza schema api --out api.schema.json

Flags of the TUI

These flags work with tiza [FILE]:

• LANG is a language id, for example rs, ts or py, or a full name such as rust.
• --step N after the last step opens the last step.
• --focus also takes A, A..B or A:B. Press Esc to clear the focus.
• --padding V sets H to two times V. Tiza does not save --padding in the document. :pad saves it.
• Follow mode is in Follow the editor.
• The themes and --theme-file are in Themes.
• Mouse capture is in Use the mouse.
• No-save mode is in Saving.

For example:

tiza examples/ownership.rs.tiza --present --step 3
tiza src/main.rs --theme light --padding 1,4

Global flags

These flags work with each command:

Tiza picks the socket from the first of these that is set:

1. --socket PATH.
2. The variable TIZA_SOCKET.
3. --session NAME.
4. The variable TIZA_SESSION.
5. The session default.

• Use a session to run two or more instances. Each instance has its own socket.
• In a session name, Tiza changes each character to _, except ASCII letters, digits, - and _.
• An empty TIZA_SOCKET or TIZA_SESSION counts as not set. An empty --session gives the socket .sock.
• tiza render uses the socket only without FILE. tiza check and tiza schema do not use it.
• The folder of the socket is in The runtime folder.
• The variables are in Environment variables.

How Tiza finds the language

Tiza uses the first of these that gives a language:

1. --lang LANG, or :lang LANG in the TUI.
2. The extension of the file, when Tiza has a grammar for it.
3. A well-known file name, for example Makefile, Dockerfile, Cargo.lock or .bashrc.
4. A #! line on the first line of the code.
5. A Vim or an Emacs modeline in the first five or the last five lines.
6. Otherwise, plain text (txt).

• Code from standard input has no file name. Thus Tiza skips items 2 and 3.
• Case does not matter in a file name or in LANG.
• When the value of --lang contains / or \, Tiza reads it as a path. It finds the language from items 2 to 6. See The language of the selected text.
• A language without a grammar shows as plain text. --lang then writes a warning on stderr.
• :lang auto finds the language again from items 2 to 6. The message tells which item gave it.
• A paste keeps the language of the code. When the code is plain text, a #! line or a modeline of the pasted text gives the language.

Tiza keeps the language in the document. :lang saves it with autosave on. --lang changes it for the session. The next save writes it. A document that you open again uses its saved language.

Check report

tiza check --json prints this report.

• min_clean_width is null when the document does not load, or when no width up to 400 shows each label.
• narrower is there only when width is under min_clean_width and no label is cut at width.
• Each finding has level, code and message. It also has id, step, file, line and text when they apply.
• file names a linked file. text is the full text of a cut label, in a clipped_label finding.

The code of a finding is one of these:

Messages

Tiza writes these messages on stderr:

• The messages no grammar for … and config ignored: … are warnings. Tiza goes on.
• When the text after the last : does not start with a digit and has other characters than digits, - and ., Tiza reads the whole text as a file name, for example a:b.rs. Then the message is could not open FILE.
• A file that is there opens as a file, also when its name has a : and a digit, for example notes 12:00.md.
• tiza: config ignored: PATH ends with the error text of the system.
• The warnings of the config file are in Warnings of the config file.
• For tiza scene text --width, the live instance checks the width. Then the message ends with (invalid_argument), as in tiza: MESSAGE (CODE).
• could not open FILE, could not read PATH and no Tiza instance is listening on … can end with the error of the system. --padding expects V or V,H can end with the reason of the error.
• The errors of tiza goto are in Messages.
• On an error, tiza exits with code 1. A wrong flag or argument exits with code 2 and prints the usage.
• tiza render to MP4 or WebM without ffmpeg also exits with code 2. See Exports.

Tiza shows these messages in the status bar:

• For a file with one line, the first message says line, not lines.
• With one annotation, the messages of the open document say annotation. When the document has more than one of these problems at start, one message gives them, with ; between them.
• After local API disabled, agents and the step commands talk to the first instance.
• The other causes of local API disabled are in The runtime folder.