Configuration

Config File Location

When starting Tattoy for the first time, the default config file is copied to your filesystem.

• Linux: $HOME/.config/tattoy/tattoy.toml.
• MacOS: $HOME/Library/Application Support/tattoy/tattoy.toml
• Windows: %LOCALAPPDATA%\tattoy\tattoy.toml.

You can start Tattoy with a custom config file using: tattoy --main-config <path/to/file>.

Because Tattoy's configuration requires a file containing the terminal palette's true colour values (palette.toml), you can also start Tattoy with an entire custom config directory using: tattoy --config-dir <path/to/directory>.

Default Config

# The command to run in Tattoy. Defaults to your current shell defined in the
# `SHELL` env var.
# command = "/usr/bin/zsh"

# The log level, one of: "off", "error", "warn", "info", "debug", "trace"
log_level = "off"
# The path to the log file. Defaults to your OS's `XDG_STATE_DIR`.
# See: https://specifications.freedesktop.org/basedir-spec/latest/
# log_path = ""

# The target frame rate
frame_rate = 30

# Whether to show a small blue indicator in the very top-right of the terminal screen.
# It can be useful to indicate that Tattoy is indeed running.
show_tattoy_indicator = true

# Whether to show the startup logo.
show_startup_logo = true

# The number of lines in the scrollback. Any lines beyond this are removed.
scrollback_size = 1000

[notifications]
enabled = true
opacity = 0.9
# The minimum level of notifications to display.
# One of: "error", "warn", "info", "debug", "trace".
level = "info"
# The amount of time in seconds to display each notification.
duration = 5.0

# Change various colour qualities of the final composited render.
[color]
saturation = 0.0
brightness = 0.0
hue = 0.0

# Automatically increases the foreground colour of alphanumeric text. This includes
# international language characters, but hopefully not common characters used in UI
# elements such as borders etc. It uses the WCAG 2.1 algorithm to define the contrast.
# For normal text on the web they recommend a minimum contrast of 4.5. Note that only
# the foreground colour is ever changed (as background colours are used for UIs). The
# target contrast is searched for by lightening, then darkening and if neither reach
# the target contrast then the larger of the 2 found contrasts is used.
[text_contrast]
enabled = true
target_contrast = 2.0
# When set to false, all text is automatically adjusted, even non-alphanumeric characters
# like UI border elements etc. The only characters that aren't adjusted are the UTF8
# half blocks (eg ▀) that are used to render "graphics", as in the shaders for example.
apply_to_readable_text_only = true

[minimap]
enabled = false
animation_speed = 0.15
# The maximum width of the minimap. It can be narrower when the scrollback is long
# in order to maintain a consistent aspect ratio.
max_width = 10

[shader]
enabled = false
opacity = 0.75
layer = -10
# Whether to render the computed shader directly to the terminal. The shader pixels can still be
# used for other purposes such as defining the foreground colour of the terminal's text,
# see `render_shader_colours_to_text`.
render = true
# Use each "cell" of the shader to set the corresponding text cell's foreground colour.
# This is most likely desirable in conjunction with the `render` option, so that the shader
# is only visible via the terminal's text.
render_shader_colours_to_text = false
# Path to a Shadertoy shader on your local filesystem. Relative to the root of Tattoy's config
# directory.
path = "shaders/soft_shadows.glsl"

[animated_cursor]
enabled = false
opacity = 1.0
# Path to the cursor shader on your local filesystem. Relative to the root of Tattoy's
# config directory.
path = "shaders/cursors/smear_fade.glsl"
# The scale of the cursor. Non-Tattoy based cursor shaders are written for cursors that are
# rendered with lots of pixels. Whereas the number of "pixels" in a Tattoy cursor is just 2,
# ie: "▀" and "▄". Imagine if a cursor shader had a design where it adds a single pixel
# border to the cursor. On say a 30x60 pixel cursor, that border would look quite good. But
# on Tattoy, that single "pixel" border suddenly makes the cursor 3 times the size! Therefore
# by default we set the cursor size to 0.0 to avoid this oversizing. However of course, not
# all cursor shaders will have this problem, so it may be useful to play with this value.
cursor_scale = 0.0
# NB: The global `frame_rate` setting can also have a significant affect on the animated cursor.

[bg_command]
enabled = false
# The command to run. The executable goes in the first position and then each argument must
# be placed in its own quotes in the array.
# Examples:
# * Render a live-updating instance of the common monitoring application "top" in the background.
#   `command = ["top"]`
# * Play the "Bad Apple" video in the background.
#   `command = ["mpv", "--really-quiet", "--vo=tct", "--volume=0", "https://www.youtube.com/watch?v=UkgK8eUdpAo"]`
command = ["echo", "Hello World"]
# Do you expect the command to exit or not?
# Usually when a command exits, Tattoy shows an error notification. But you may want to render a
# command that outputs some static content, for example to print out some ASCII-based image:
#   `command = ["chafa", "/path/to/wallpaper.png"]`
# Bear in mind that there's currently no config to re-run the command on terminal resize.
expect_exit = false
opacity = 0.75
layer = -5

[keybindings]
# Whether Tattoy renders anything apart from the TTY. The TTY is always rendered,
# so toggling this will disable all tattoys, effects, eye-candy, etc.
toggle_tattoy = { mods = "ALT", key = "t" }
# Toggle scolling mode whilst in scrollback.
toggle_scrolling = { mods = "ALT", key = "s" }
# Show/hide the minimap.
toggle_minimap = { mods = "ALT", key = "M" }
# Scroll up in the scrollback 
scroll_up = { key = "UpArrow" }
# Scroll down in the scrollback 
scroll_down = { key = "DownArrow" }
# Exit scrolling mode
scroll_exit = { key = "Escape" }
# Cycle to previous shader in user's shader config directory
shader_prev = { mods = "ALT", key = "9" }
# Cycle to next shader in user's shader config directory
shader_next = { mods = "ALT", key = "0" }