Command-Line Interface

Run termvisage --help to see the basic help message or termvisage --long-help for the full help message.

Note

Some options are only applicable in a specific mode. If used with the other mode, they’re simply ignored.

Shell Completion

Run termvisage --completions for instructions on enabling tab completion for options and arguments of termvisage in your preferred shell.

Options and Arguments

usage: termvisage [--help | --long-help] [--version] [--completions]
                  [--query-timeout N] [-S {auto,block,iterm2,kitty}]
                  [--force-style] [-C N | --auto-cell-ratio]
                  [--swap-win-size | --no-swap-win-size] [--cli | --tui]
                  [-f N] [-R N]
                  [--anim-cache N | --cache-all-anim | --cache-no-anim]
                  [--no-anim] [--no-alpha | -A N | -b [COLOR]] [--h-allow N]
                  [--v-allow N] [--scroll] [-O]
                  [-w N | -h N | --fit | --fit-to-width | --original-size | -s N | -x N | -y N]
                  [--no-align] [-H {left,center,right}] [--pad-width N]
                  [-V {top,middle,bottom}] [--pad-height N] [-a] [-r] [-d N]
                  [--thumbnail | --no-thumbnail] [--max-pixels N]
                  [--multi | --no-multi] [--config FILE | --no-config]
                  [-l FILE]
                  [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL} | -q | -v | --verbose-log | --debug]
                  [--kz N] [--kc N] [--itn] [--itnmb N] [--itc N] [--itjq N]
                  [--itnrff]
                  [source ...]

-- should be used to separate positional arguments that begin with an - from options/flags, to avoid ambiguity. For example, $ termvisage [options] -- -image.jpg --image.png.

See https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html for supported image formats.

See https://termvisage.readthedocs.io/en/stable/cli.html for the complete CLI description.

Positional Arguments

source

Image file path(s), directory path(s) and/or image URL(s). If no source is provided, the current working directory is used.

General Options

--help

Show the basic help message and exit

--long-help

Show this help message and exit

--version

Show the program version and exit

--completions

Show instructions to enable shell completions and exit

--query-timeout <n>

Timeout (in seconds) for all terminal queries (default: query timeout config)

-S {auto,block,iterm2,kitty}, --style {auto,block,iterm2,kitty}

Image render style (default: style config) [1]

--force-style

Use the specified render style even if it’s reported as unsupported by the active terminal

-C <n>, --cell-ratio <n>

The cell ratio (width-to-height ratio of a character cell) in the terminal; to preserve image aspect ratio (default: cell ratio config)

--auto-cell-ratio

Determine the cell ratio from the terminal emulator, if possible (default: cell ratio config)

--swap-win-size, --no-swap-win-size

Enable/Disable a workaround for auto cell ratio on some terminal emulators (e.g older VTE-based ones) that wrongly report window dimensions swapped (default: swap win size config)

--cli

Do not launch the TUI. Instead, draw all image sources to the terminal directly [2]

--tui

Launch the TUI, even for a single image

Animation Options (General)

-f <n>, --frame-duration <n>

The time (in seconds) between frames for all animated images (default: determined per image from the metadata OR 0.1)

-R <n>, --repeat <n>

Number of times to repeat all frames of an animated image; A negative count implies an infinite loop (default: -1)

--anim-cache <n>

Maximum frame count for animation frames to be cached (Better performance at the cost of memory) (default: anim cache config) [3]

--cache-all-anim

Cache frames for all animations (beware, the higher the frame count per image, the higher the memory usage)

--cache-no-anim

Disable frame caching (Less memory usage but reduces performance)

--no-anim

Disable image animation. Animated images are displayed as just their first frame.

Transparency Options (General)

NOTE: These are mutually exclusive

--no-alpha

Disable image transparency (alpha channel is removed)

-A <n>, --alpha <n>

Alpha ratio above which pixels are taken as opaque (0 <= x < 1), for text-based render styles (default: 0.156863)

-b <color>, --alpha-bg <color>

Hex color (without #) to replace transparent backgrounds with (omit COLOR to use the active terminal's default BG color)

CLI-only Options

These options apply only when there is only one valid image source or --cli is specified

--h-allow <n>

Horizontal allowance i.e minimum number of columns to leave unused (default: 0)

--v-allow <n>

Vertical allowance i.e minimum number of lines to leave unused (default: 2)

--scroll

Allow an image’s height to be greater than the terminal height. Not needed when --fit-to-width is specified.

-O, --oversize

Allow an image’s size to be greater than the terminal size (To be used with -w or --original-size)

Sizing Options (CLI-only)

These apply to all images and are mutually exclusive [4]

-w <n>, --width <n>

Image width

-h <n>, --height <n>

Image height

--fit

Fit each image optimally within the available terminal size

--fit-to-width

Fit each image to the available terminal width, --v-allow has no effect i.e vertical allowance is ignored

--original-size

Render each image using its original size (See -O, USE WITH CAUTION!)

-s <n>, --scale <n>

Image scale (overrides -x and -y) [5]

-x <n>, --scale-x <n>

Image horizontal scale (overridden by -s) (default: 1.0)

-y <n>, --scale-y <n>

Image vertical scale (overridden by -s) (default: 1.0)

Alignment Options (CLI-only)

These apply to all images

--no-align

Output image without alignment or padding. Overrides all other alignment options.

-H {left,center,right}, --h-align {left,center,right}

Horizontal alignment (default: center)

--pad-width <n>

Number of columns within which to align each image (default: terminal width, minus horizontal allowance)

-V {top,middle,bottom}, --v-align {top,middle,bottom}

Vertical alignment (default: middle)

--pad-height <n>

Number of lines within which to align each image (default: none)

TUI-only Options

These options apply only when there is at least one valid directory source, multiple valid sources or --tui is specified

-a, --all

Include hidden file and directories

-r, --recursive

Scan for local images recursively

-d <n>, --max-depth <n>

Maximum recursion depth (default: 950)

--thumbnail, --no-thumbnail

Enable or disable thumbnail generation for the image grid; if enabled, thumbnails are cached on disk and cleaned up upon exit (default: thumbnail config)

Performance Options

--max-pixels <n>

The maximum pixel-count for images that should be rendered (default: max pixels config)

--multi, --no-multi

Enable (if supported) or disable multiprocessing (default: multi config)

Config Options

NOTE: These are mutually exclusive

--config <file>

The config file to use for this session (default: Searches XDG Base Dirs)

--no-config

Use the default configuration

Logging Options

NOTE: All these, except -l, are mutually exclusive

-l <file>, --log-file <file>

The file to write logs to (default: log file config)

--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}

Logging level for the session (default: WARNING) [6]

-q, --quiet

No notifications, except fatal errors

-v, --verbose

More detailed event reporting. Also sets logging level to INFO

--verbose-log

Like -v but only applies to the log file

--debug

Implies --log-level=DEBUG with verbosity

Kitty Style Options

These options apply only when the kitty render style is used

--kz <n>, --kitty-z-index <n>

Image stacking order [CLI-only]; >= 0 -> above text, < 0 -> below text, < -(2**31)/2 -> below cells with non-default background (default: 0)

--kc <n>, --kitty-compress <n>

ZLIB compression level; 0 -> no compression, 1 -> best speed, 9 -> best compression (default: 4)

iTerm2 Style Options

These options apply only when the iterm2 render style is used

--itn, --iterm2-native

Use the protocol’s animation support; animations will not be skipped [CLI-only]

--itnmb <n>, --iterm2-native-max-bytes <n>

Maximum size (in bytes) of image data for native animation [CLI-only] (default: 2097152)

--itc <n>, --iterm2-compress <n>

ZLIB compression level, for images re-encoded in PNG format 0 -> no compression, 1 -> best speed, 9 -> best compression (default: 4)

--itjq <n>, --iterm2-jpeg-quality <n>

JPEG compression status and quality; < 0 -> disabled, 0 <= x <= 95 -> quality (default: -1) [7]

--itnrff, --iterm2-no-read-from-file

Never use image data directly from file; always re-encode images [8]

Footnotes

[1]

See Render Styles.

[2]

In CLI mode, only image sources are used, directory sources are skipped. Animated images are displayed only when animation is disabled (with --no-anim), when there’s only one image source or when using native animation of some render styles.

[3]

Frames will not be cached for any animation with more frames than this value. Memory usage depends on the frame count per image, not this maximum count.

[4]

The size is multiplied by the scale on respective axes when an image is rendered. A scale value must be such that 0.0 < value <= 1.0.

[5]

Width and height are in units of columns and lines respectively.

By default (i.e if none of the sizing options is specified), the equivalent of --original-size is used if not larger than the available size, else --fit.

[6]

Any event with a level lower than the specified one is not reported.

[7]

0 -> worst quality; smallest data size, 95 -> best quality; largest data size.

By default (i.e when disabled), PNG format is used for re-encoding images, which has less compression with better quality. JPEG encoding:

• reduces render time & image data size and increases drawing speed on the terminal’s end but at the cost of image quality and color reproduction.

• is useful for animations with high resolution and/or sparse color distribution.

• only applies when an image is re-encoded and not read directly from file (see --itnrff).

• can only be used for non-transparent images but the transparency status of some images can not be correctly determined in an efficient way at render time.

  Thus, to ensure the JPEG format is always used for re-encoded images, disable transparency (--no-alpha) or set a background color (-b).

[8]

By default, image data is used directly from file when no image manipulation is required. Otherwise, it’s re-encoded in PNG (or JPEG, if enabled) format.

The optimization significantly reduces render time when applicable but does not apply to animations, native or not.