Options Reference

This chapter documents every flag accepted by uplot, organized by category. All flags listed under “common plot options” apply to every command that renders a plot. Input and output options are global and apply regardless of the command. Command-specific options are listed in the relevant Commands Reference subsections.

Common plot options

These flags control the appearance and layout of the rendered plot. They are available on all plotting commands (bar, count, hist, line, lines, scatter, density, box).

Note that -h is used for height, not help. Use --help to display the help text.

Border styles

The four border styles control the frame drawn around the plot area:

• solid draws a complete box with continuous lines on all four sides. This is the default for most plot types.
• corners draws only the four corner pieces, leaving the sides open. This is the default for box plots.
• barplot is like solid but replaces the left side border with tick marks. This is the default for bar charts, count plots, and histograms.
• ascii uses ASCII characters (+, -, |) instead of Unicode box-drawing glyphs, for terminals with limited Unicode support.

Color specification

The -c flag accepts several color formats:

• Named colors: black, red, green, yellow, blue, magenta, cyan, white, and their light variants (light_red, light_blue, etc.). gray and grey are aliases for light_black.
• ANSI 256-color index: a number from 0 to 255 (e.g., -c 128).
• RGB triple: three comma-separated values from 0 to 255 (e.g., -c 255,0,128).

When no color is specified, series colors are assigned automatically from the palette (green, blue, red, magenta, yellow, cyan), cycling for additional series.

Input options

These global flags control how input data is parsed. They apply to all commands that read from stdin.

Delimiter

The default delimiter is a tab character. To read comma-separated data, use -d, (no space between the flag and the comma). Any single byte character can be used as a delimiter.

Transpose

The -T flag swaps rows and columns before any other processing. This is useful when your data is arranged with series in rows rather than columns. For example, if you have a file where each row is a named series:

temperature	22	24	23	25	26
humidity	45	50	48	52	55

Use -T to transpose it so that each column becomes a series.

Headers

The -H flag tells uplot to treat the first record as column headers rather than data. Headers are used for axis labels, legend names, and plot titles depending on the command. When combined with -T, the first column of each row is treated as the header for that series.

Encoding

By default, uplot expects UTF-8 input. The --encoding flag allows reading files in other character encodings. The encoding name should be a standard label recognized by the WHATWG Encoding Standard (e.g., UTF-16, Shift_JIS, ISO-8859-1). The input is decoded into UTF-8 before parsing.

Grid plot options

These flags apply to the grid-based commands: line, lines, scatter, and density.

The --fmt flag controls how multi-column input is interpreted. For single-series commands (line), xy means the first column is x and the second is y, while yx swaps them. For multi-series commands (lines, scatter, density), xyy treats the first column as shared x values with subsequent columns as separate y series, while xyxy pairs columns as x1,y1,x2,y2 so each series has its own independent x values.

Output options

These global flags control where the rendered plot and the raw input data are sent.

Plot routing (-o)

By default, the rendered plot is written to stderr. This allows you to pipe data through uplot without the plot interfering with the data stream on stdout.

• -o (no value): redirect the plot to stdout instead of stderr
• -o FILE: write the plot to a file

Data passthrough (-O)

The passthrough flag copies the raw input data to a separate destination, which is useful for tee-like workflows where you want to both visualize and forward data:

• -O (no value): copy the raw input to stdout
• -O FILE: copy the raw input to a file

A common pattern is to render a plot to stderr (the default) while passing the data through to the next pipeline stage:

cat data.tsv | uplot line -O | further-processing

Color mode

The -C and -M flags override the automatic terminal detection. They are mutually exclusive; specifying both produces an error. Without either flag, uplot emits ANSI color codes when the output destination is a terminal and omits them when writing to a file or pipe.