CHA(1)

📦
version 0.5.0 · 3 versions
, in arch rolling

🌸 NAME — cha, the Chawan text-mode browser, and yes this is CHA(1) 🌸

Okay bestie, meet cha — the Chawan text-mode browser. She’s the main character of this manual page, and this is CHA(1) serving full “I read the docs and slayed” energy. 💅✨

🦋 SYNOPSIS 🦋

cha [options] [URL(s) or file(s)...]

💖 DESCRIPTION 💖

Chawan is a text-mode browser, no cap. You can use it as a pager, or as a web/(S)FTP/gopher/gemini/file browser. It understands HTML and CSS, and when enabled by the user, it can also execute JavaScript and display images — on terminals supporting Sixel or the Kitty image protocol. 🎀🦋

Chawan can also be used as a general text-based document viewer as described in cha-mailcap(5), or as a hyperlinked man page viewer using mancha(1). It’s giving versatile icon behavior. 👑

This page is literally all about the invocation of Chawan. For a list of default keybindings, type cha about:chawan. For a detailed description of the configuration format, see cha-config(5). iykyk. ✨

🍓 ARGUMENTS 🍓

On invocation, Chawan attempts to open all URL/file arguments supplied. If no URLs could successfully be opened, Chawan exits automatically. Very “if nobody shows up to the party, I’m leaving” of her. 😭

Chawan may also be started without specifying a file, if a file is provided through a pipe. In this case, you can specify the content type using the -T switch. Pipe her in, bestie. 🫶

✨ OPTIONS ✨

All command line options have short forms (e.g. -d) and long forms (e.g. --dump). Two names, one iconic option. 💅

Long forms must be introduced with two dashes; when only a single dash is provided, each letter is parsed as a separate short form. So don’t be out here giving long options one lonely dash — she will read every letter as its own short form. 💀

In short form, it is also valid to provide values to arguments without a subsequent space. For example, -obuffer.images=true is valid. Sneaky little no-space slay. 🎀

  • -c, --css stylesheet — Temporarily modify the user stylesheet. If a user stylesheet is already being used, the stylesheet given is appended to that. It’s giving “quick outfit change, but make it CSS.” 💖
  • -d, --dump — Start in headless mode, and sequentially print the opened files to stdout. This option is implicitly enabled if stdout is not a tty (e.g. when piping cha output). Headless era activated. 👑
  • -h, --help — Print a short version of this page, then exit. A lil appetizer before the full meal. 🍓
  • -o, --opt config — Pass temporary configuration options. This accepts the configuration format described in cha-config(5), so the passed string must be valid TOML.

To ease specifying string parameters, unrecognized bare keywords are converted to strings. So this works: --opt display.color-mode=eight-bit.

Symbols and words starting with a number must still be quoted, i.e. you have to quote them twice to bypass shell quoting.

For options whose name does not appear in any other section, skipping the section name is valid. For instance, to enable buffer.images, you can type -o images=true.

However, this may stop working in future versions if images is added to another section, so it shouldn’t be relied upon in scripts. > Heads up, bestie: cute shortcut, but not a forever promise for your scripts. 💀

  • -r, --run script/file — Execute the string provided as a JS script, or execute the supplied JS file. If the file ends in .mjs, it is executed as an ES module. JavaScript girlies rise. 🔥
  • -v, --version — Print information about the browser’s version, then exit. Version check, then bye. 💅
  • -C, --config file — Override the default configuration search path. Both absolute and relative paths are allowed. Path freedom, periodt. 🌈
  • -I, --input-charset charset — Override the character set of all input files. Useful when Chawan is incorrectly recognizing the input character set.

(If this happens often, consider changing the default input charset recognition list encoding.document-charset in the configuration.) Fix it at the source, icon. ✨

  • -M, --monochrome — Force monochrome output. Formatting (bold/italic/etc.) is not affected. This is a shortcut for -o display.color-mode=monochrome. Monochrome but make it still formatted. 🖤
  • -O, --output-charset charset — Override the output character set. This is a shortcut for -o encoding.display-charset=charset. Output charset, but make it a shortcut. 🎀
  • -T, --type content-type — Override the content type of all input files. Useful when the content type cannot be guessed from the file extension, or when reading a non-plaintext file from stdin. When the file extension is not giving, you gotta tell her yourself. 🫶
  • -V, --visual — When no files/URLs are passed, open the page specified in start.visual-home instead of printing a help screen. No arguments? No problem — visual home page time. 🌸
  • -- — Interpret all following arguments as files. For example, you can open a file named -o using cha -- -o. The “stop reading these as options” barrier has entered the chat. 💅

🌈 ENVIRONMENT 🌈

Certain environment variables are read and used by Chawan. She’s nosy in the most useful way. 👀

  • TMPDIR — When set, the default configuration stores temporary files inside this directory (and /tmp/cha-tmp-user otherwise.) Temporary file realness. 🎀
  • HTTP_HOME, WWW_HOME — When set, Chawan starts in visual mode by default and opens the page specified by one of these variables. HTTP_HOME takes precedence over WWW_HOME. Two home variables walk in; HTTP_HOME wins. 👑
  • CHA_DIR — When set, it switches the configuration directory to the path specified. New config directory, who dis. ✨
  • COLORTERM — When set to 24bit or truecolor, and the display.color-mode configuration option is set to auto, Chawan sets the color mode to true color. Color mode glow-up unlocked. 🌈
  • TERM — Used by Chawan to adjust to terminal-specific quirks. When not set, defaults to xterm. Terminal quirks get handled, bestie. 💅
  • VISUAL, EDITOR — Used to determine the editor to use when the external.editor configuration option is not set. Editor selection fallback squad. 🫶
  • LINES, COLUMNS — Used as fallback values when window size detection fails. When the terminal won’t tell her the size, these step in. 😭

🦋 SEE ALSO 🦋

Cute sign-off from the CHA(1) footer corner: General Commands Manual vibes, with CHA(1) as the footer and no separate source/version/date line listed beyond that. We close the page exactly as the footer intended, bestie. 💖✨💅

📦 where this page comes from