CHAFA(1)

📦
version 1.18.3 · 12 versions
, in fedora 43, fedora 44

💖 CHAFA 💖

okay bestie, welcome to the chafa manual, section 1 of the User Commands — and yes the manual name is CHAFA(1), we're not being subtle about it 🎀 this is the "Character art facsimile generator" and she is that girl. ✨

🌸 NAME 🌸

chafa — Character art facsimile generator 🦋

✨ SYNOPSIS ✨

chafa [OPTION...] [IMAGE...]

That's the whole thing. Options first, then your images. Clean, simple, slay. 💅

💜 DESCRIPTION 💜

okay so picture this: chafa is a command-line utility that converts image data — and literally yes, that includes animated GIFs, we love her 💖 — into graphics formats or ANSI/Unicode character art suitable for display in a terminal.

her feature support is broad. like, broad broad. she works on devices ranging from historical teleprinters all the way to modern terminal emulators and everything in between. the range?? the way she just... does it all?? no cap, she's the moment. 👑

You can specify one or more input files, no problem, BUT — and this is the part you need to write down bestie ✍️ — the default behavior is slightly different with multiple files. for instance, animations will not loop forever when there is more than one input file. so if your GIF is behaving differently than you expected when you stacked files, that's why. not a bug, it's a feature, periodt.

🎀 GENERAL OPTIONS 🎀

  • --files path — Read a list of paths to process from path, or - for stdin. The paths must be separated by newlines. 📝

Can be specified multiple times. Any additional paths on the command line will be processed last.

  • --files0 path — Same idea as --files, but read from path, or - for stdin, with the paths separated by NUL bytes instead. This is more robust if your file system allows newlines in filenames (as POSIX does, and she's just being thorough 💅). Super useful in conjunction with other tools that support it, e.g.:
find . -type f -print0 | chafa --files0 -

Can be specified multiple times. Any additional paths on the command line will be processed last.

  • -h, --help — Show a brief help text. short, sweet, helpful. 🫶
  • --probe arg — Probe the terminal's capabilities and wait for response [auto, on, off]. A positive real number denotes the maximum time to wait for a response, in seconds. Defaults to 5.0. ⏳
  • --probe-mode mode — How to probe the terminal [any, ctty, stdio]. "Any" is the default and will probe by any means available. "Ctty" will probe the controlling tty, usually /dev/tty, which is useful when chafa is part of a pipeline — but heads up, this may block if done in the background 😭. "Stdio" will only consider standard input/output. pick your fighter. 🥊
  • --version — Show version, feature and copyright information. the receipts, the credentials, the whole résumé. 👑

🌈 OUTPUT ENCODING 🌈

  • -f, --format format — Set output format; one of [iterm, kitty, sixels, symbols]. The default is iterm, kitty or sixels if the connected terminal supports one of these, falling back to symbols (that's your "ANSI art") otherwise. ✨
  • -O num, --optimize num — Compress the output by using control sequences intelligently [0-9]. 0 disables, 9 enables every available optimization. Defaults to 5, except for when used with "-c none", where it defaults to 0. so like, the higher the number the more she flexes. 💅
  • --relative bool — Use relative cursor positioning [on, off]. When on, control sequences will be used to position images relative to the cursor. When off, newlines will be used to separate rows instead for e.g. 'less -R' interop. Defaults to off.
  • --passthrough mode — Graphics protocol passthrough [auto, none, screen, tmux]. Used to show pixel graphics from within multiplexers. Defaults to auto, which will enable passthrough if the Kitty terminal is detected along with one of the supported multiplexers. Other combinations must be enabled manually; use with the -f option to select the appropriate graphics protocol. 🔀
  • --polite bool — Polite mode [on, off]. Inhibits escape sequences that on rare occasions may confuse the terminal or other programs. Defaults to off. she's on her best behavior only when asked, and honestly? mood. 🎀

🦋 SIZE AND LAYOUT 🦋

  • --align ALIGN — Align images in viewport. The following alignments are understood: left, right, top, bottom, hcenter, vcenter, center. Two orthogonal alignments can be separated by a comma, e.g. "center,right". The meaning of "center" depends on context, and defaults to "hcenter" if ambiguous. "center,center" will center along both axes. 📐

Centering vertically makes sense when used together with "--clear", or possibly as part of a scheme where the cursor is pre-positioned at the top-left corner of the view, or a subview when used with "--relative on".

  • -C bool, --center bool — Center images horizontally in the view [on, off]. Defaults to off. This option is deprecated; use "--align center" instead. 👵 (she's old, be nice, use the new one)
  • --clear — Clear screen before processing each file. fresh slate every time, we love a clean start. 🧼
  • --exact-size mode — Try to match the input's size exactly [auto, on, off]. When on, this will override other sizing options and produce output images at the exact pixel size of the inputs. In auto mode, scaling will be avoided (in exchange for padding) if the output size is equal to or slightly bigger than the input. When off, padding will never be added, and the image is scaled to fit the containing cell extent. Defaults to auto. 📏
  • --fit-width — Fit images to the view's width, potentially exceeding its height. width said yes, height said we'll see. 😌
  • --font-ratio width/height — Target font's width/height ratio. Can be specified as a real number or a fraction. Defaults to 1/2. This will only be applied in symbol mode. 🔤
  • --grid colsxrows — Lay out images in a grid of cols columns and rows rows per screenful. Either cols or rows may be omitted, e.g. --grid 4 or --grid x4, in which case cell allocations will be approximately square. If "auto" is specified, dimensions will be picked automatically. ✨
  • -g — Alias for "--grid auto". the shortcut, the little treat. 🍓
  • --label bool — Labeling [on, off]. When this is enabled, each image will be labeled with its filename. Defaults to off. nametags but make it pixels. 🏷️
  • -l — Alias for "--label on".
  • --margin-bottom num — When terminal size is detected, reserve at least this many rows at the bottom as a safety margin. Can be used to prevent images from scrolling out. Defaults to 1. 🛟
  • --margin-right num — When terminal size is detected, reserve at least this many columns on the right-hand side as a safety margin. Defaults to 0.
  • --scale num — Scale image, respecting terminal's maximum dimensions. 1.0 approximates original pixel dimensions. Specify "max" to use all available space. Defaults to 1.0 for pixel graphics and 4.0 for symbols. 🔍
  • -s widthxheight, --size widthxheight — Set maximum output image dimensions in columns and rows. By default this will be equal to the view size (see --view-size).
  • --stretch — Stretch image to fit output dimensions; ignore aspect. Implies --scale max. she will not be respecting the aspect ratio, she's going full send. 🔥
  • --view-size widthxheight — Set the view size in columns and rows. By default this will be the size of your terminal, or 80x25 if size detection fails. If one dimension is omitted (by providing a size of e.g. 80x or x25), it will be set to a reasonable approximation of infinity. ♾️

⏰ ANIMATION AND TIMING ⏰

  • --animate bool — Whether to allow animation [on, off]. Defaults to on. When off, will show a still frame from each animation. she can move, she can freeze. range! 💃
  • -d, --duration seconds — Time to show each file, in seconds. Defaults to zero for still images and for animations when multiple files are specified. If a single animation is specified, defaults to infinite, or "inf". Animations will always be played through at least once, even if duration is e.g. zero. See the "Duration" section for more. 🔁
  • --speed speed — Set the speed animations will play at. This can be either a unitless multiplier (fractions are allowed), or a real number followed by "fps" to apply a specific framerate. 🏃‍♀️
  • --watch — Watch a single input file, redisplaying it whenever its contents change. Will run until manually interrupted or, if --duration is set, until it expires. 👀 she's always watching, bestie.

🌈 COLORS AND PROCESSING 🌈

  • --bg color — the background color of the display, bestie. Say it as a color name or a hex value. Any partially transparent parts of your input get blended against this, so it's giving backdrop realness. Color names are based on the ones X.Org ships with. Defaults to black, or — when probing is turned on — the terminal's own default background (peep --probe).
  • -c mode, --colors mode — tells chafa what color mode to output in. Pick one of [none, 2, 8, 16/8 16, 240, 256, full]. Okay important tea: the 240-color mode is genuinely the recommended one over 256, because the lower 16 colors are unreliable and tend to differ between terminals (they're messy fr). The 16-color mode uses aixterm extensions to produce 16 foreground and background colors. The 16/8 mode does 8 colors plus another "bright" 8 in the foreground, implemented with the "bold" escape sequence. The 2-color mode only emits the ANSI codes for reverse color and attribute reset, while "none" emits no escape sequences at all — zero, nada. 💅

And in sixel mode? "full" dynamically generates a 256-color palette for each image or animation frame. The other modes refer to built-in palettes. Note that "none" and "2" are interchangeable and will use the foreground/background colors you specified (go see --fg and --bg). If you leave it unspecified, chafa picks an optimal default based on the current environment. She's adaptive like that. ✨

  • --color-extractor extractor — the method for pulling color out of an area; one of [average, median]. median normally produces crisper output, while average may do better on noisy images. Defaults to average.
  • --color-space cs — the color space used for quantization; one of [rgb, din99d]. Defaults to rgb, which is faster but less accurate. Trade-offs, bestie.
  • --dither type — the type of dithering to apply during quantization. One of [none, ordered, diffusion, noise]. Heads up: "Bayer" is a synonym for "ordered", and "fs" (Floyd-Steinberg) is a synonym for "diffusion". Defaults to "noise" in sixel mode, otherwise "none".
  • --dither-grain widthxheight — the dimensions of the grain used while dithering. You write it as width x height, where each one can be one of [1, 2, 4, 8] pixels. For the record: one character cell is, by definition, 8 pixels across in both dimensions. Defaults to 4x4 in symbol mode and 1x1 in sixel mode.
  • --dither-intensity intensity — how intense the dithering pattern is. It ranges from 0.0 to infinity, with 1.0 considered neutral. Lower values tend to reduce how much dithering gets done, higher values crank it up. Realistically though? Values higher than 10.0 are unlikely to produce useful results, so maybe don't. 😭
  • --fg color — the foreground color of the display (color name or hex). Together with the background color from --bg, this is what specifies the terminal's palette in color modes 2 and none. Color names are based on the ones X.Org provides. Defaults to white, or — when probing is on — the terminal's default foreground (see --probe).
  • --invert — inverts the video, specifically for displaying with bright backgrounds in color modes 2 and none. It swaps --fg and --bg. Iconic behavior honestly.
  • -p bool, --preprocess bool — image preprocessing [on, off]. Defaults to on when you're at 16 colors or lower, and off otherwise. What it does is enhance colors and contrast before conversion, which is super useful in low-color modes. Glow-up for your pixels. ✨
  • -t threshold, --threshold threshold — the threshold above which full transparency gets used [0.0 - 1.0]. Living on the edge here: setting it to 0.0 will render a blank image, while a value of 1.0 will replace any transparency with the background color (which you can configure with --bg). Choose wisely. 🫶

🎀 RESOURCE ALLOCATION 🎀

  • --threads num — the maximum number of CPU threads to use. If you leave it unspecified or set it negative, it'll just equal however many CPU cores you have available. Free real estate.
  • -w num, --work num — how hard chafa should work, in terms of CPU and memory, on a scale of [1-9]. 1 is the cheapest, 9 is the most accurate. Defaults to 5. The classic "how much do you care" dial. 💅

🦋 EXTRA OPTIONS FOR SYMBOL ENCODING 🦋

  • --fg-only — leaves the background color untouched. This produces character-cell output using foreground colors only, and avoids resetting or inverting the colors. Clean and minimal, we love her.
  • --fill symbols — specify the character symbols to use for fill/gradients. Defaults to none. Usage is similar to --symbols — go look below for the full rundown.
  • --glyph-file file — loads glyph info from file, which can be any font file FreeType supports (TTF, PCF, etc). The glyph outlines here will replace any existing outlines, builtins included. This is useful in symbol mode for custom font support, or for boosting quality with one specific font. Real talk though: it only makes sense if your output terminal is actually using a matching font. Can be specified multiple times. 🌸
  • --symbols symbols — specify which character symbols to employ in the final output. Full usage plus the whole list of symbol classes is right below. 👇

💀 EXIT STATUS 💀

chafa returns 0 on success, 1 on partial failure, or 2 on complete failure — and yes, that includes when you invoke it with no arguments at all. Not me getting hit with a 2 on an empty command. 😭

  • 0 — Success
  • 1 — Some files failed to display
  • 2 — All files failed to display

🔤 SYMBOLS 🔤

The accepted classes for --symbols and --fill are [all, none, space, solid, stipple, block, border, diagonal, dot, quad, half, hhalf, vhalf, inverted, braille, technical, geometric, ascii, legacy, sextant, wedge, wide, narrow]. Some symbols belong to multiple classes — for example, diagonals are also borders. Crossover icons, honestly.

You can add specific characters by writing the letter "u" followed by a hexadecimal code point, like "ue080". Or you can add a whole range of code points by separating the first and last index with "..", like "u100..u200". Periodt.

Symbol sets can also be specified as a string of UTF-8 characters inside square brackets, like [abcd]. And if you need to include a closing bracket in the set, just escape it with a backslash.

You can give a list of classes separated by commas, or prefix them with + and - to add or remove symbols relative to the existing set. Heads up: the ordering is significant. Ordering always matters. 👑

The default symbol set is block+border+space-wide-inverted for all modes except "none", which uses block+border+space-wide (including inverse symbols).

⏳ DURATION ⏳

To accommodate both interactive use and batch processing, an animation's duration gets determined by a few simple rules:

  1. If one or more --duration arguments are present, the final instance is respected and applied to every file.
  2. Otherwise, if there's a controlling terminal attached (which signals there's an interactive session), and only a single file argument is provided, and that file is an animation, it will have infinite duration. She just keeps going, bestie.
  3. Otherwise (no controlling terminal, multiple files, or the file is a still image), duration will be zero — which causes animations to play once and then stop.

✨ EXAMPLES ✨

chafa in.gif

chafa in.gif

Shows a potentially animated GIF image right there in your terminal. If it is an animation, it'll run until the user generates an interrupt (typically ctrl-c). All parameters get autodetected based on the current environment. Effortless. 🌈

chafa -c full -s 200 in.gif

chafa -c full -s 200 in.gif

Same vibe as above, but it forces truecolor output that's 200 characters wide, and calculates the height while preserving the aspect ratio of the original image. Math ate.

chafa -c 16 --color-space din99d --symbols -dot in.jpg

chafa -c 16 --color-space din99d --symbols -dot in.jpg

Generates 16-color output with perceptual color picking, and avoids using dot symbols. No dots allowed. 🚫

chafa -c none --symbols block+border-solid in.png

chafa -c none --symbols block+border-solid in.png

Generates uncolored output using block and border symbols, but avoids the solid block symbol.

📚 FURTHER READING 📚

See the Chafa homepage[1] for more info. Go read, you'll love it.

👑 AUTHOR 👑

Written by Hans Petter Jansson[2] <hpj@hpjansson.org>.

📝 NOTES 📝

  1. Chafa homepage — https://hpjansson.org/chafa/
  2. Hans Petter Jansson — https://hpjansson.org/

Okay that's the whole page bestie, we made it to the end 🎉 — this was chafa's entry in section CHAFA(1), and big thanks to Hans Petter Jansson for writing it and giving it a home at hpjansson.org and hpjansson.org/chafa/. Go forth and render all the things. 💖🦋✨

📦 where this page comes from