kuva CLI

kuva is the command-line front-end for the kuva plotting library. It reads tabular data from a TSV or CSV file (or stdin) and writes an SVG — or PNG/PDF with the right feature flag — to a file or stdout.

kuva <SUBCOMMAND> [FILE] [OPTIONS]

Installation

Step 1 — install Rust

If you don't have Rust installed, get it via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Follow the on-screen prompts (the defaults are fine). Then either restart your shell or run:

source ~/.cargo/env

Verify with cargo --version. You only need to do this once.

kuva itself only needs Rust 1.87. The one exception is PDF output: --features pdf/full pulls in krilla, which requires Rust >= 1.92. If rustup show reports an older version and you plan to use --features full or pdf, run rustup update first.

Step 2 — install kuva

From crates.io (recommended once a release is published):

cargo install kuva --features cli          # SVG output
cargo install kuva --features cli,full     # SVG + PNG + PDF

From a local clone (install to ~/.cargo/bin/ and put it on your $PATH):

git clone https://github.com/Psy-Fer/kuva && cd kuva

cargo install --path . --features cli          # SVG output
cargo install --path . --features cli,full     # SVG + PNG + PDF

After either method, kuva is available anywhere in your shell — no need to reference ./target/release/kuva or modify $PATH manually. Confirm with:

kuva --help

Building without installing

If you only want to build and run from the repo without installing:

cargo build --release --bin kuva --features cli,full
./target/release/kuva --help

Input

Every subcommand takes an optional positional FILE argument. If omitted or -, data is read from stdin.

# from file
kuva scatter data.tsv

# from stdin
cat data.tsv | kuva scatter

# explicit stdin
kuva scatter - < data.tsv

Delimiter detection

Header detection

The first row is treated as a header when either its first field fails to parse as a number, or some column holds a non-numeric label sitting atop an otherwise all-numeric column (so a leading numeric key column no longer hides the header, e.g. 5,data above 0,1 / 1,2).

Two flags override the auto-detection (they are mutually exclusive):

• --header: force the first row to be a header even if it looks like data (useful for all-numeric column names such as years).
• --no-header: force the first row to be data even if it looks like a header.

Column selection

Columns are selected by 0-based integer index or header name:

kuva scatter data.tsv --x 0 --y 1          # by index
kuva scatter data.tsv --x time --y value   # by name (requires header)

An all-numeric column name (such as a year) works too. A bare numeric argument is read as an index first; if that index is out of range and the file has a header column literally named by that number, it selects that column instead:

kuva scatter expression.tsv --x 2023 --y 2024 --header   # columns named "2023" / "2024"

In-range indices are never reinterpreted, so --x 0 always means the first column. This bare-number fallback only resolves names whose numeric value exceeds the column count (years and similar).

To remove the ambiguity entirely, prefix the value:

name: is the way to select a column whose name is a small number that would otherwise be read as an index (e.g. a column literally named 1 in a 5-column file: --x name:1). idx: forces a pure index, so an out-of-range idx: errors rather than falling back to a name. Prefixes work on every column argument (--x, --y, --value-col, --group-col, --color-by, --axes, …) in every subcommand.

Ranges and globs (multi-column arguments)

Multi-column arguments (--y, --value-cols, --samples, --axes) also accept index ranges and name globs, which expand to several columns at once:

You can mix all forms in one comma-separated list (duplicates are removed, order preserved):

kuva line data.tsv --x date --y "y1,sum_*"      # y1 plus every sum_* column
kuva line data.tsv --x 0 --y 3..                 # column 3 to the last
kuva box  data.tsv --y "a*"                       # a single glob is a valid multi-column selection

A single glob or range on its own still routes into the plot's multi-column (grouped/overlaid) path. Globs need a header row; a glob that matches nothing is an error. Ranges are index-based. (For --value-cols/--axes, which take space-separated values rather than commas, pass each selector as its own value: --value-cols a1 b*.)

Missing values (scatter, line, histogram, bar, parallel)

Empty cells, cells holding a missing-value token (NA, NaN, null, N/A, . by default, case-insensitive), and non-finite values (inf, -inf) are treated as missing rather than aborting the command (non-finite values would otherwise corrupt axis ranges). A cell that is neither empty, a token, nor a number is still an error, so selecting the wrong column is caught.

• --na-strategy <drop|zero|error>: what to do with a missing value in a selected numeric column. drop (default) removes the row and prints a one-line note; zero replaces it with 0; error restores the old strict behaviour.
• --na-values <tokens>: comma-separated tokens to treat as missing, replacing the default set. Empty cells are always missing. Accepts negative sentinels, e.g. --na-values -999,NA.
• --clamp-min <N> / --clamp-max <N>: clip numeric values to a bound. Finite values outside the bound are clipped, and crucially +inf becomes the max and -inf becomes the min, so an infinite value can be capped at a real number rather than dropped. A common case is capping an infinite -log10(p) (from a p-value of exactly 0): --clamp-max 300. If only one side is set, an infinity on the other side stays missing.

kuva scatter data.tsv --x time --y value                 # drops rows with missing x or y
kuva histogram data.tsv --value-col v --na-strategy zero # missing -> 0
kuva scatter data.tsv --x pos --y logp --clamp-max 300   # +inf -> 300 instead of dropped

Parquet input

Every subcommand that reads tabular data also accepts .parquet files, not just scatter or any single subcommand: parquet support lives in the shared input layer every subcommand goes through, so it applies uniformly across all of them.

kuva scatter data.parquet --x x --y y -o plot.svg
cat data.parquet | kuva histogram --value-col value    # also detected via stdin

Requires building with the parquet feature (cargo build --features cli,parquet, or cli,full,parquet for every backend). Without it, a .parquet file is read as plain text and will fail to parse.

Detection is automatic, no flag needed:

Column selection (--x, --y, --value-col, etc.) works identically to CSV/TSV, by index or header name. Under the hood, only the requested columns are decoded from disk (a projected Arrow read), so memory and time scale with the columns you actually select rather than the full schema, useful for wide parquet files with many unused columns.

--header, --no-header, and --delimiter are ignored for parquet input (with a warning) since parquet is self-describing: it always carries its own schema and column names, so there's no header row to skip and no delimiter to guess.

Output

Format is inferred from the file extension case-insensitively. Output paths must end in .svg, .png, or .pdf; other or missing extensions are rejected before input is read.

Shared flags

These flags are available on every subcommand.

Output & appearance

Fonts

By default, SVG output references fonts by name and relies on the viewer to resolve them. This works fine in browsers and on any system where DejaVu Sans, Verdana, Liberation Sans, or Arial is installed. In environments with no system fonts — headless servers, containers, CI pipelines — text may be missing or fall back to an unexpected face.

--embed-font bakes DejaVu Sans as a base64 @font-face block into the SVG <style> element, making the file fully self-contained at the cost of roughly 1 MB of extra size. PNG and PDF output is unaffected: those backends always have the font available regardless of this flag.

# Self-contained SVG for use with rsvg-convert or similar tools in containers
kuva scatter data.tsv --x x --y y --embed-font -o plot.svg

# Pipe into rsvg-convert in a minimal container
kuva scatter data.tsv --x x --y y --embed-font | rsvg-convert -o plot.png

SVG interactivity

When --interactive is set the output SVG contains a self-contained <script> block with no external dependencies. Features:

• Hover tooltip — hovering a data point shows its label and value.
• Click to pin — click a point to keep its highlight; click again or press Escape to clear all pins.
• Search — type in the search box (top-left of the plot area) to dim non-matching points. Escape clears.
• Coordinate readout — mouse position inside the plot area is shown in data-space coordinates.
• Legend toggle — click a legend entry to show/hide that series.
• Save button — top-right button serialises the current SVG DOM (including any pinned/dimmed state). Note: the download is not yet functional.

Supported in this release: scatter, line, bar, strip, volcano. All other subcommands accept --interactive and load the UI chrome (coordinate readout, search box) but do not yet have per-point hover/search — full renderer coverage is planned for a future release.

kuva scatter data.tsv --x x --y y --color-by group --legend --interactive -o plot.svg
kuva volcano hits.tsv --gene gene --log2fc log2fc --pvalue pvalue --legend --interactive -o volcano.svg

Terminal output

Terminal output uses Unicode braille dots (U+2800–U+28FF) for scatter points and continuous curves, full-block characters (█) for bar and histogram fills, and ANSI 24-bit colour. Terminal dimensions are auto-detected from the current tty; pass --term-width and --term-height to override (useful in scripts or when piping).

# Scatter plot directly in terminal
kuva scatter data.tsv --x x --y y --terminal

# Explicit dimensions
kuva bar counts.tsv --label-col gene --value-col count --terminal --term-width 120 --term-height 40

# Manhattan plot on a remote server
cat gwas.tsv | kuva manhattan --chr-col chr --pvalue-col pvalue --terminal

Note: Terminal output is not yet supported for upset. Running kuva upset --terminal prints a message and exits cleanly; use -o file.svg instead.

Axes (most subcommands)

Log scale (scatter, line, histogram, density, hist2d)

Date/time X axis (scatter, line)

Default tick format per unit (used when --x-date-tick-format is omitted):

# Auto mode: format and unit picked from the data range
kuva line prices.tsv --x date --y close --x-date-format "%Y-%m-%d"

# Explicit unit and tick format
kuva scatter prices.tsv --x date --y close \
    --x-date-format "%Y-%m-%d" --x-date-unit months --x-date-tick-format "%b %y"

# One tick every 2 weeks
kuva line prices.tsv --x date --y close \
    --x-date-format "%Y-%m-%d" --x-date-unit weeks --x-date-tick-step 2

See Reference → Date & Time Axes for the underlying DateTimeAxis API.

Secondary Y axis (twin-y)

Input

Subcommands

All 57 subcommands, grouped the same way plot pages are grouped in the sidebar. Each link goes straight to that subcommand's CLI section at the bottom of its library-equivalent page, right next to the Rust API it wraps — so full per-flag documentation, usage examples, and the builder reference live together on one page instead of two.

Distributions

Relationships & correlation

Categorical & comparison

Time series

Statistical & model evaluation

Hierarchical & network

Genomics & bioinformatics

3D

Composite & Utility

Tips

Pipe to a viewer:

kuva scatter data.tsv | display            # ImageMagick
kuva scatter data.tsv | inkscape --pipe    # Inkscape

Quick PNG without a file:

kuva scatter data.tsv -o /tmp/out.png      # requires --features png

Themed dark output:

kuva manhattan gwas.tsv --chr-col chr --pvalue-col pvalue \
    --theme dark --background "#1a1a2e" -o manhattan_dark.svg

Colour-vision-deficiency palette:

kuva scatter data.tsv --x time --y value --color-by group \
    --cvd-palette deuteranopia