Configuration

The full dog reference — every flag, environment variable, exit code, and config path, including the 17 supported languages.

Synopsis

dog [OPTIONS] [FILE]
echo CODE | dog -l LANGUAGE

The first form renders a file — auto-detection picks the language from the filename, extension, or shebang, and flags can go before or after the file. The second form reads code from stdin; with no filename to detect from, -l names the language, taking any name or alias from supported languages. More stdin recipes live in stdin and shebang detection.

Arguments

[FILE]

Path to a file. Optional. When omitted, dog reads from stdin.

Options

Input / output

--language, -l String

Force a language. Overrides auto-detection. Accepts canonical names and aliases from supported languages.

When reading from stdin, -l is the most reliable way to set the language — see stdin and shebang detection.

Default: auto-detect.

--color auto | always | never

When to emit ANSI color.

• auto — color in a TTY, plain when piped
• always — color in all destinations
• never — no color

Respects NO_COLOR and FORCE_COLOR.

Default: auto.

Themes

--theme String

Theme name. dog looks first at the two built-ins (UtilityDark, UtilityBright), then at JSON files in the theme directory. For multi-variant Zed bundles, pass the variant name (e.g. Catppuccin Mocha).

A theme file works too — any of these read the file directly, skipping the name search:

• --theme Nord.json — a file in the theme directory
• --theme ~/.config/zed/themes/Nord.json — a path (~/ and ${VAR} expand)
• --theme 'Nord:Nord Dark' — file:variant, picking one variant out of a multi-variant file (.json optional, paths work too)

A file without a :variant means its first variant.

--theme wins over --dark and --light when both are set.

For picking, installing, and authoring themes, see Theming.

Default: UtilityDark, or your saved --set-default-theme choice.

--dark

Shortcut for the UtilityDark built-in. This is the default, so you don't need to pass it. No JSON parsing, no file I/O.

Can't be combined with --light (errors if both are passed). Overridden by an explicit --theme.

--light

Shortcut for the UtilityBright built-in. Same zero-cost path as --dark.

Can't be combined with --dark (errors if both are passed). Overridden by an explicit --theme.

--theme-dir Path

Theme search directory. Supports ~/ expansion and ${VAR} substitution.

Common workflow: point this at an existing Zed themes directory — see using existing Zed themes.

Default: $XDG_CONFIG_HOME/dog/themes → $HOME/.config/dog/themes.

--set-default-theme String

Save a theme as the default, then exit. Takes anything --theme takes — a name, a file, a path, or file:variant — resolves it once, and saves the finished theme to the default theme file. Every later run loads it in microseconds, with no JSON parsing.

The saved default applies when no --theme, --dark, or --light is passed.

Clear it with an empty value ('') or by naming the built-in default (UtilityDark) — both reset dog to the built-in.

Default: not set.

Paging

--paging auto | always | never

Pager policy. Long output is piped through less -R when paging is active and stdout is a TTY.

• auto — page when output exceeds terminal height
• always — page whenever possible
• never — don't page

Default: auto.

INFO

The pager is hardcoded to less -R. $PAGER is not honored in 0.1.

For using dog inside previewers (fzf, tv, yazi), disable the pager — see pager behavior.

--no-pager, -P

Equivalent to --paging=never.

Formatting

--wrap, -w auto | never

Line-wrap mode.

• auto — wrap when stdout is a TTY or --terminal-width is set
• never — emit full lines

When piped into a previewer (fzf, tv, yazi), dog defaults to no-wrap and truncates long lines at the pane edge. Pass --wrap=never explicitly if you want to force that behavior — see using dog with fzf.

Default: auto.

--terminal-width Int

Override the detected terminal width in columns. Clamped to the real terminal width.

--plain, -p stackable

Strip decorations. Stackable:

• -p — no decorations
• -pp — no decorations, no pager

Useful in shell pipelines where decorations interfere — see shell pipes.

--line-numbers / --no-line-numbers stub

Planned. Line numbers are currently always on in decorated output — the flags parse but have no effect yet. To get output without line numbers today, strip decorations with --plain.

Information

--list-themes, -T

Print bundled and user themes with their variant names, then exit.

--list-languages, -L

Print the canonical name of every supported language, then exit. Aliases are listed in supported languages.

--woof

Browse embedded language snippets rendered with the current theme.

• With fzf available and stdout is a TTY: interactive language picker with live preview.
• Without fzf or when piped: prints a sample.
• -l <lang> renders a single language instead of opening the picker.

The fzf preview workflow is documented in using dog with fzf.

--version

Print the version and exit.

--help, -h

Print usage and exit.

Exit codes

Code	Meaning
0	Success
1	File error, parse error, theme error
2	Bad usage (e.g. unknown language)
64	Flag errors (unknown flag, conflicting flags)

Environment variables

NO_COLOR

Non-empty, non-0 value disables color in --color=auto mode. See https://no-color.org.

FORCE_COLOR

Non-empty, non-0 value forces color. Wins over NO_COLOR.

TERM

Terminals announce what they are through TERM. A value of dumb means whatever is running dog can't display colors — Emacs shell buffers and some CI systems set it — so dog skips color in --color=auto mode.

XDG_CONFIG_HOME

When set to an absolute, non-empty path: base for the default theme directory and the config file (planned).

HOME

Used for ~/ expansion and as the XDG fallback root.

DOG_LOG_LEVEL debug builds only

Controls the internal Bark logger. Release builds ignore this.

Paths

Theme directory

Resolution order:

1. --theme-dir <path> (supports ~/ and ${VAR})
2. $XDG_CONFIG_HOME/dog/themes
3. $HOME/.config/dog/themes

Default theme file

--set-default-theme saves the resolved theme to:

1. $XDG_CONFIG_HOME/dog/default-theme
2. $HOME/.config/dog/default-theme

Deleting the file resets dog to the built-in default. An unreadable file (say, one written by an older dog) never blocks rendering — dog warns, uses the built-in, and a fresh --set-default-theme run rewrites it.

Config file planned

TOML config at $XDG_CONFIG_HOME/dog/config.toml is planned. Not shipped in 0.1.

When shipped, precedence will be: flags > config file > defaults.

Supported languages

17 languages ship by default. Each is an SE-0450 package trait; a custom build can include only selected traits.

Canonical	Aliases
bash	sh, shell, shell-script, zsh
c	—
cpp	c++
css	—
go	golang
html	xhtml
javascript	js, node
json	geojson, jsonl, sarif, topojson
lua	—
markdown	md, pandoc
python	py, py3, python3
ruby	rb, jruby, macruby, rake
rust	rs
swift	—
tsx	typescriptreact
typescript	ts, bun, deno, ts-node
yaml	yml

Highlight queries from nvim-treesitter (Apache 2.0), inheritance chains pre-resolved.

Detection cascade

When --language is not set, dog runs four stages and stops at the first match:

1. Explicit flag — -l <lang>.
2. Exact filename — 64 filenames (e.g. Gemfile, Package.swift, .bashrc, Cargo.lock).
3. Extension — 78 extensions. .h resolves to cpp.
4. Shebang — 40 interpreters (python, node, bun, ruby, swift, etc.). Handles env with flags and version suffixes (python3.11 → python3).

Backup suffixes are stripped once before the extension retry: ~, .bak, .backup, .old, .orig, .save, .in, .dpkg-dist, .dpkg-new, .dpkg-old, .dpkg-tmp, .ucf-dist, .ucf-new, .ucf-old, .rpmnew, .rpmorig, .rpmsave. So config.yaml.bak resolves to yaml.

---

🐕 Dog Fact

A greyhound hits 45 mph within six strides from a standstill. dog needs about six milliseconds.