Reference

Config file

The config file holds your own settings for every session. It gives the values that a session starts with, your personal styles and your theme colors. This page tells where Tiza finds the file, what each key does, which value wins, and what Tiza does with a wrong entry.

An example

This file sets every key of [defaults], one personal style and one color for each theme:

[defaults]
pad = "1 2"
numbers = false
mouse = true
autosave = false
layout = "stable"
width = 120
effect_fps = 30

[styles.decision]
glyph = "◆"
legend = "decision"
color = "purple"

[theme.dark]
accent = "#a6e3a1"

[theme.light]
accent = "#b7410e"

Put the file at ~/.config/tiza/config.toml. Then run tiza config to see what Tiza takes from it.

A config file is optional. Each key is optional too. A key that the file does not set keeps its built-in value.

Where Tiza finds the file

Tiza takes the path of the file from the first item of this list that applies:

1. $TIZA_CONFIG, when it is set.
2. $XDG_CONFIG_HOME/tiza/config.toml, when that variable is set.
3. ~/.config/tiza/config.toml.

• An empty TIZA_CONFIG, XDG_CONFIG_HOME or HOME counts as not set. A TIZA_CONFIG with only spaces also counts as not set.
• Without HOME and without XDG_CONFIG_HOME, Tiza reads no config file.
• When no file is at the path, Tiza uses the built-in values.
• When TIZA_CONFIG names a file that does not exist, Tiza also writes a warning.
• When Tiza cannot read the file, it ignores the file and writes tiza: config ignored: PATH.
• When a part of the file has an error, Tiza ignores only that part. See Warnings.

When Tiza reads the file

• The TUI reads the file only when it starts. A change to the file applies at the next start.
• tiza config only shows the file. It changes nothing.
• Without a FILE argument, tiza render exports the live instance. Then it takes the width and numbers from the instance, and only [theme] from the config file.
• tiza mcp reads its own config file: the file that its environment gives, not the file of the instance. export_image takes numbers from the instance.
• tiza check uses numbers for the gutter when the document does not set it.
• The check method of the socket and the check MCP tool use the width of the config file of the instance.

[defaults]

The values that a session starts with.

• pad = "V" sets H to two times V. A number, for example pad = 2, does the same. pad = "default" gives the built-in value.
• numbers, mouse and autosave also take the strings "on", "off", "yes" and "no".
• pad changes only the screen. An export does not draw the padding.
• In presentation mode, the layout is always stable.
• effect_fps changes only the screen. A GIF, a WebP or a video plays an effect at 25 frames each second.

Which value wins

A flag, a : command and the document win over the config file. The config file wins over the built-in value. The config file never writes a value into the document.

• pad: --padding wins over the padding of the document for the session. :pad V H saves the padding in the document. :pad default removes it from the document. Then the padding of the config file applies. When the file has no pad, the built-in value applies.
• numbers: When the document has a numbers field, it wins over the config file. :numbers on and :numbers off always write the field, also when the gutter is already in that state. Then the document looks the same on a computer without your config file. To use the config file again, remove the field from the .tiza file.
• mouse: Mouse capture is on at start when you give --mouse or the file sets mouse = true. The file cannot turn off --mouse. :mouse changes it for the session.
• autosave: --no-save wins over autosave = true. :autosave changes it for the session. :autosave on also ends no-save mode.
• layout: :layout changes it for the session.
• width: For tiza render and tiza check, --width wins, then the file, then 100. For the check method and the check MCP tool, their width argument wins, then the file of the instance, then 100.
• effect_fps: Only the file sets it, for every session.

[styles]

Your personal styles. Each [styles.NAME] table is one style, with the fields of :style. Use a personal style as a kind: :mark NAME, or kind of an agent's add_mark.

• The color names and their aliases are in Color names.
• The name of a style cannot be empty and cannot have spaces.
• The name of a style cannot be a built-in kind or an alias, for example warn or todo. Personal styles do not change the built-in kinds. The kinds and the aliases are in Kinds.

When a personal style goes into the document

The first time that a mark uses a personal style, Tiza copies the style into the document. Then the .tiza file looks the same on a computer without your config file.

• Tiza copies the style when a mark of that kind comes into the document: :mark, an agent's add_mark, a change of a mark to that kind, scene.put or scene.patch.
• When the document has a style with the same name, the style of the document wins. Tiza does not copy the personal style.
• :style NAME with glyph=, legend= or color= on a personal style changes a copy of it in the document. The config file does not change.
• :mark shows ID: LEGEND at LN (style NAME from config.toml) when it copies a style.

[theme]

Your theme colors. The [theme] table sets color tokens for every theme. The subtables [theme.dark], [theme.light] and [theme.terminal] set them for one theme. The tokens and their values are in Themes.

• The document wins over the config file. The config file wins over the built-in theme.
• When a text color of [theme] is too faint on the background, Tiza changes it to a color with more contrast. tiza config lists each of these changes as a warning, with its theme.

tiza config

tiza config shows the config file in use, each value of [defaults] with its source, the personal styles, the [theme] tokens and the warnings. It changes nothing.

With the file of An example, it shows:

file: /home/dev/.config/tiza/config.toml
defaults:
  pad        1 2      config
  numbers    off      config
  mouse      on       config
  autosave   off      config
  layout     stable   config
  width      120      config
  effect_fps 30       config
styles (config; a document style with the same name wins):
  decision ◆  decision  @purple
theme (config): [dark] accent = #a6e3a1, [light] accent = #b7410e
warnings: none

• The file: line gives the path of the file. Without a file, it gives file: none (no file at PATH): every value is built-in. Without HOME and without XDG_CONFIG_HOME, it gives file: none (no home folder): every value is built-in.
• In defaults:, the source of each value is config or built-in. A flag, a : command and the document can still win over it. See Which value wins.
• The warnings are the lines that Tiza writes on stderr, without tiza: config: .
• tiza config exits with 0, also when the file has warnings. It exits with 1 when Tiza cannot read the file. Then it writes tiza: config: PATH: ERROR.

Warnings

Tiza never stops because of the config file. When it cannot use an entry, it ignores that entry and writes a warning. The other entries apply.

• The TUI, tiza render and tiza check write each warning on stderr. Each line starts with tiza: config: , and then gives the path and the line of the entry.
• The TUI writes these lines before it takes the screen. You see them after you quit.
• At start, the status bar shows the first warning, then (N warnings: tiza config). That warning has the form NAME:LINE: KEY: …: the file name without its folder, and the key without its table.
• tiza config lists all the warnings. See tiza config.
• The JSON reply of export_image has a warning field. It says what the config file left out, or that Tiza cannot read the config file.

• KEYS lists the keys of [defaults]. FIELDS lists the fields of a style. COLORS lists the color names.
• After 200 keys that are in the file two times, one warning gives the number of the other ones.
• ERROR is the text of the TOML reader. tiza: config ignored: PATH ends with the error text of the system.
• Some warnings make Tiza ignore more lines than the line of the entry. For example, Tiza ignores a table that it does not read, and all the entries of that table. Then the warning ends with , so Tiza ignores lines A-B. Any warning of the table can have this end. The list of lines can also be line N or lines A-B and C.
• The warnings about [theme] are in Themes.

For example, a file with six errors gives these warnings:

tiza: config: /home/dev/.config/tiza/config.toml:2: [defaults] width: 5 is not valid: use a number of columns between 20 and 400
tiza: config: /home/dev/.config/tiza/config.toml:3: [defaults] colour: unknown key (keys: pad, numbers, mouse, autosave, layout, width, effect_fps)
tiza: config: /home/dev/.config/tiza/config.toml:5: [defaults] numbers: duplicate key, the first value is used
tiza: config: /home/dev/.config/tiza/config.toml:7: [styles] risk: a style needs a glyph, so Tiza ignores lines 7-9
tiza: config: /home/dev/.config/tiza/config.toml:11: unclosed table, expected `]`: the table header has an error, so Tiza ignores lines 11-12
tiza: config: /home/dev/.config/tiza/config.toml:16: this line is not valid UTF-8: Tiza ignores its entries

When a file has the same key 203 times, Tiza writes a warning for each of the first 200 copies. Then it writes:

tiza: config: /home/dev/.config/tiza/config.toml:203: 2 more keys that are in the file two times: Tiza uses the first value of each

A folder at the path of the file gives:

tiza: config ignored: /home/dev/.config/tiza/config.toml: Is a directory (os error 21)