gloss

Install

Mon, 01 Jan 0001 00:00:00 +0000

Install#

With Homebrew, on macOS or Linux:

brew install --cask nimblemarkets/tap/gloss

On Debian or Ubuntu, download the .deb for your machine from the latest release and install it:

sudo apt install ./gloss_*_linux_amd64.deb # or _arm64

The release also has archives for macOS, Linux, and Windows (amd64 and arm64), each a single binary with nothing else to install. With Go, go install github.com/NimbleMarkets/gloss/cmd/gloss@latest builds it from source.

For agents#

If you are installing gloss for an AI agent, also install its skill, which teaches the agent the headless interface (--text, --output, --info, --pick, --serve):

Using gloss

Mon, 01 Jan 0001 00:00:00 +0000

Using gloss#

gloss shows the files you name, or the contents of a folder, or what you pipe into it. With no file it opens empty: drop files on it, or press o to browse.

gloss photo.png drawing.svg report.pdf model.stl
gloss --menu photo.png report.pdf model.stl # a menu to choose among them
gloss --preview photo.png report.pdf model.stl # the menu, with a preview pane

Kitty graphics are selected automatically on supporting terminals, with colored half-block glyphs as a fallback. The program uses the alternate screen and restores the terminal on exit. With -X (--no-alt-screen, as in less) it draws on the main screen instead: the scrollback is left alone, and the last view stays where it was drawn when you quit. The choice can wait until you quit: q quits as launched, and Q quits leaving the last view in the scrollback either way, so a picture worth keeping beside the next command stays, and one that is not does not. Direct PNG transport works over SSH; no shared filesystem or external converter is needed. In tmux, enable passthrough with set -g allow-passthrough on.

Controls

Mon, 01 Jan 0001 00:00:00 +0000

Controls#

Key	Action
`q`, `Ctrl-C`	Quit
`q`, `Q`	Quit / quit leaving the last view in the scrollback, whatever `-X` said
`?`, `Esc`	Show help / dismiss help
`Esc`	Back to the file list, with previews, from a document
`t`	In the file list, show the files as a grid of thumbnails, and back
`m`	Open the file-selection menu
`o`, `O`	Browse folders for a file to open
`]`, `Tab` / `[`, `Shift-Tab`	Next / previous file
`n`, `Space`, `PageDown` / `p`, `b`, `PageUp`	Next / previous PDF page, sheet, or Grist table; next / previous file for other formats
`/`	Search text in the current document; `Enter` submits, `Esc` cancels editing
`n` / `N`, while searching	Next / previous result, wrapping at the ends; `Esc` clears the search
`Home` / `End`, `G`	First / last PDF page
Arrows, `h j k l`	Move about a spreadsheet by row and column
`x`, `X`	Hide the column under the cursor / show every column
`c`	List the columns, to show and hide them: `Space` toggles, `a` all, `n` none
`Enter`	With `--fetch`, open the web address under the cursor
`u`	Show a QR code for the selected table URL; `Esc` or `u` closes it, `g` switches graphics, `e` exports the QR
`Esc`	Close a fetched file and return to its cell
`+`, `-`	Zoom in / out
Arrows, `h j k l`	Pan zoomed images; orbit meshes
`f`, `0`	Fit image / reset camera
`g`	Toggle Kitty / glyph output when Kitty is supported
`R`	Reload file from disk
`e`	Export the current page as a PNG in the working directory (a download in a browser)
`i`	Show or hide a box of details about the current file and the terminal
`r`	Toggle mesh auto-rotation; reload other formats
`5`	Toggle mesh orthographic / perspective projection
`c`	List the parts of a 3MF: `Space` shows or hides one, `Enter` focuses on it, `a` all, `n` only it
`X`	Show every part of a 3MF again
`C`	Pick a color for a mesh: `Tab` between palette, sliders, and hex; `Space` applies the swatch, `Enter` chooses the swatch you have moved to and closes, `r` (the Reset button) restores the file’s colors, `s` paints all faces or only plain ones, `Esc` undoes
`B`	Pick the background color behind a mesh, with the same picker as `C`: `r` restores the default, `Enter` chooses the swatch you have moved to and closes, `Esc` undoes
Click, in the `C` / `B` picker	Click a tab, swatch, or slider bar; a swatch applies at once and a second click on it chooses it and closes; drag along a slider
Drag / Shift-drag / wheel	Mesh (STL, 3MF) orbit / pan / zoom
Drop files, or paste their paths	Add files to the list; one opens at once, several open the menu

At a PDF boundary, page navigation stays on that page. Use [ and ] to change files. Loading and rendering run asynchronously; errors appear in the viewer with retry and next-file controls.

Opening and viewing

Mon, 01 Jan 0001 00:00:00 +0000

Opening and viewing#

How gloss starts and what it draws with: the file menu and preview pane, terminal graphics, the screen it uses, which files it finds, and what it may fetch. gloss never fetches the network on its own.

Option	Argument	Default	Description
`-m`, `--menu`			start with the file-selection menu
`-P`, `--preview`			start with the file menu and a preview pane
`-r`, `--render`	`string`	`"auto"`	terminal graphics: auto, kitty, glyph
`-X`, `--no-alt-screen`			draw on the main screen: scrollback is kept, and the last view stays after quitting
`-t`, `--type`	`string`		force input type: image, svg, pdf, stl, 3mf, docx, xlsx, grist, csv, json, ipynb, html, text, markdown (or md)
`--glob`	`stringArray`		search the folders named, or the current one, for files: a glob, an extension, or a kind such as images (repeatable)
`--fetch`			allow opening a dropped URL or a table address with Enter; gloss never fetches on its own

Examples#

# Look at some files, with a menu to choose among them
gloss --menu photo.png report.pdf model.stl

# A menu with a preview pane
gloss --preview *.png

# Every image under the current folder
gloss --glob images

# A file whose name does not say what it is
gloss --type markdown notes

Documents, pages and tables

Mon, 01 Jan 0001 00:00:00 +0000

Documents, pages and tables#

Choosing the page of a PDF or the sheet of a workbook, how finely a PDF is drawn, and which columns of a table to show.

Option	Argument	Default	Description
`-p`, `--page`	`string`	`"1"`	PDF page or workbook sheet, from 1; for an export or text into a folder, a range such as 2-5, or all
`-d`, `--dpi`	`int`	`150`	PDF rasterization DPI (36–600)
`--cols`	`string`		show only these columns of a table, by header or letter: name,name
`--coln`	`string`		show only these columns of a table, counted from 1: 2,4-6

Examples#

# The third page of a PDF
gloss --page 3 report.pdf

# Sharper pages
gloss --dpi 300 report.pdf

# Only some columns of a sheet, by header or by number
gloss --cols name,total sales.xlsx
gloss --coln 2,4-6 sales.csv

Meshes: STL and 3MF

Mon, 01 Jan 0001 00:00:00 +0000

Meshes: STL and 3MF#

How a model is drawn and posed: the renderer, the camera or a named view, the projection, its paint, and which parts of a 3MF are shown. These apply to exports as well as to the viewer.

Option	Argument	Default	Description
`--3d`	`string`	`"auto"`	mesh renderer for STL and 3MF: auto, software, wireframe
`--view`	`string`		views of a mesh: front, back, left, right, top, bottom, iso, all; several, as front,top, export as one sheet
`--camera`	`string`		camera for a mesh, as elevation,azimuth or elevation,azimuth,distance in degrees
`--projection`	`string`	`"ortho"`	projection of a mesh: ortho, perspective
`--color`	`string`		paint the faces of a mesh its file left plain: #rrggbb or a name such as orange
`--parts`	`string`		show only these parts of a 3MF, by name: name,name
`--partn`	`string`		show only these parts of a 3MF, counted from 1: 2,4-6

Examples#

# Start from the front, in perspective
gloss --view front --projection perspective model.stl

# Paint the faces the file left plain
gloss --color orange model.stl

# Two parts of a 3MF, by name or by number
gloss --parts lid,base lantern.3mf
gloss --partn 1,3 lantern.3mf

Exporting images

Mon, 01 Jan 0001 00:00:00 +0000

Exporting images#

Writing PNGs without a terminal, sized for the vision models that will read them. Export never overwrites a file; it numbers the name instead. --max-edge is the stable way to size an image; --vision-profile is only an alias for one.

Option	Argument	Default	Description
`-o`, `--output`	`string`		export one input as PNG; ‘-’ writes PNG to stdout
`-O`, `--output-dir`	`string`		export each input as a numbered PNG in this directory
`-s`, `--max-edge`	`int`	`1536`	maximum exported image edge in pixels (1–4096)
`--vision-profile`	`string`		alias for a –max-edge, which is stable where these go stale: claude-high, claude-standard, openai-high

Examples#

# One page, as a PNG
gloss --page 2 --output page2.png report.pdf

# Every page, into a folder
gloss --page all --output-dir pages report.pdf

# A contact sheet of a model's views, to a pipe
gloss --view front,top,iso --output - model.stl > sheet.png

Text and details

Mon, 01 Jan 0001 00:00:00 +0000

Text and details#

Reading a file without drawing it: its text, or what it says about itself, or where a PDF says something. All work without a terminal and write only the answer to standard output. With --json, a PDF page’s text comes with chars and images, and sparse when it is a picture with next to no text, better exported with --output. --grep prints each match’s page and a line around it, not the document.

Handing files over, and showing them

Mon, 01 Jan 0001 00:00:00 +0000

Handing files over, and showing them#

Asking the user for a file, or showing them one, when the caller has no terminal of its own: an agent, for instance. --pick prints the paths the user sends; --serve shows them a page. Without a terminal on standard input both detach, print one line of JSON, and are answered later with --resume, which waits for the answer. --status asks at once, as JSON, how the pick stands, and changes nothing; it still answers after --resume. --cancel ends the session, deleting its folder. All three take the resume token, not the one in the page’s address.

The file browser

Mon, 01 Jan 0001 00:00:00 +0000

The file browser#

The file browser is how you find a file to open without leaving gloss. It is a fast, keyboard-first chooser with a mouse as well: it filters as you type, completes paths with Tab, lays folders out in columns like a file manager, and keeps a sidebar of places. Everything it offers has a key, and none of it changes a file: it only looks, and hands back what you choose.

Teaching agents: gloss skill

Mon, 01 Jan 0001 00:00:00 +0000

Teaching agents: gloss skill#

gloss skill has no options of its own. gloss carries a skill that teaches an agent its headless surface, so it always matches the flags this binary has. gloss skill prints it, as gloss skill show does; gloss skill install writes it where the agents on this machine look, or into the skills folder named.

Examples#

# Install it for the agents found on this machine
gloss skill install

# Or into the skills folder named
gloss skill install ~/.claude/skills

# Print it, to place by hand
gloss skill

General

Mon, 01 Jan 0001 00:00:00 +0000

General#

Help and version. gloss help is the usage, and gloss help skill that of a command.

Option	Argument	Default	Description
`-h`, `--help`			show help
`-V`, `--version`			print version

Asking for a file

Mon, 01 Jan 0001 00:00:00 +0000

Asking for a file#

A program that cannot show a terminal, such as an agent working for you, can still ask you for a file, or show you one:

gloss --serve --pick # prints the paths you send, one to a line
gloss --serve report.pdf # shows you the file; prints nothing
gloss --pick # the same question, asked in the terminal

--serve starts a temporary server on this machine, opens the viewer on a page in your browser, and ends when you quit the viewer or close the tab. The page is the native viewer, not the demo: o browses your own folders, and a pasted path is read from your disk. Files dropped on the page are handed to gloss.

Markdown

Mon, 01 Jan 0001 00:00:00 +0000

Markdown#

Open .md, .markdown, or .mdown files, or pipe text with --type markdown. Glamour renders headings, lists, tables, and syntax-highlighted code. Local Markdown image references (including reference-style links) use the existing raster and SVG renderers, shown as block figures following their text line. Paths resolve relative to the Markdown file, or the working directory for stdin. Missing and remote images show placeholders; HTML image tags are not rendered.

gloss examples/readme.md
gloss --preview examples/readme.md examples/shapes.svg
cat README.md | gloss --type markdown -

Use j/k, arrows, or the mouse wheel to scroll; Space/b page down/up; Ctrl-D/Ctrl-U move half a page; Home/End jump to the ends. Press s to switch between rendered Markdown and source. File navigation remains [/]. Documents are limited to 2 MiB of UTF-8 and 32 image references, with a combined 16-megapixel decoded image budget after resizing. Embedded images fit within 1600 pixels. Markdown PNG export is not supported: send Markdown text directly to a model and export individual images when needed.

For agents

Mon, 01 Jan 0001 00:00:00 +0000

For agents#

skills/gloss/SKILL.md teaches an agent gloss’s headless surface, in the order an agent needs it: --text, a sized PNG export, --info --json, then --pick or --serve. The binary carries it, so it always matches the flags it was built with:

gloss skill install # install it for the agents found on this machine
gloss skill install ~/.claude/skills # or into the skills folder named
gloss skill # print it, to place it by hand

Or, with Node, the skills CLI installs it from the repository for every agent it finds:

Formats and limits

Mon, 01 Jan 0001 00:00:00 +0000

Formats and limits#

PNG, JPEG, WebP, BMP, TIFF: first frame/page, up to 32 megapixels. Animated WebP and AVIF aren’t supported.
GIF: automatic playback with transparency, partial frames, disposal, and the file’s loop count. Space pauses/resumes (or restarts after the last loop); </> select 0.25×, 0.5×, 1×, 2×, or 4× speed; Backspace restores 1×. r reloads from the beginning at 1×. The status bar shows the frame, speed, and playback state. e exports the current full frame as PNG; zoom/pan still work. Canvas size is limited to 32 MP, animation to 1,000 frames and 64 Mi decoded frame pixels in total. Limits are checked before decoding all frames. Delays below 20 ms use 100 ms before the speed multiplier is applied; other delays are scaled directly (minimum 5 ms at 4×). Rendering can slow playback on large images or slow terminals; frames are not queued up. File-list previews, inline Markdown/notebook images, and headless --output use the first frame on the full logical canvas. GIF frames are not --pages.
HEIC/HEIF: primary still image, up to 32 megapixels, with container rotation and mirroring. Uses the pure-Go h265 decoder, without CGO or external converters. Unsupported HEVC features report decoder errors. HEIC works in Markdown, previews, PNG exports, and the browser demo.
SVG: NTCharts’ pure-Go SVG renderer, rasterized to a 2400-pixel maximum edge. SVG support follows the underlying oksvg renderer, not a full browser engine.
PDF: PDFium via embedded WebAssembly; no Poppler, MuPDF, CGO, or external runtime installation. Pages render at 150 DPI by default (--dpi 36..600), with a 32-megapixel raster budget and a 10,000-page limit. Password-protected PDFs aren’t supported. / searches the text layer and jumps to matching pages with excerpts; it does not highlight the raster or perform OCR.
STL: ASCII and binary, flat-shaded triangles, up to 932,067 faces: as many as NTCharts3d draws, which is as many as any GPU is sure to hold. Normals are recomputed from vertex winding. GPU rendering falls back to software and then wireframe. Software draws at full size for Kitty output, smaller only while its frames are slow, and samples meshes above 20,000 triangles; wireframe samples above 2,000 triangles, so large models can lose detail in fallback modes.
Mesh color: an STL, and the faces of a 3MF its file leaves plain, are drawn in one default blue. C opens a color picker over the mesh: a palette of swatches, one slider per channel, or a hex number typed in, each change painted as it is made; Enter chooses the swatch you have moved to (or keeps the color set) and closes, changing nothing if you have not moved; Esc undoes it. A 3MF with colors of its own is recolored whole, and the picker’s Reset button (or r) gives its colors back; s limits the paint to the faces its file left plain. --color #rrggbb, or a name such as orange, paints the viewer and exports alike.
3MF parts: what the build places is listed by name, from the model or the slicer’s settings, and c opens that list over the mesh: Space shows or hides a part, Enter shows it alone with the camera fitted to it, n keeps only it, a and X bring all back. --parts name,name and --partn 2,4-6 choose parts for the viewer, an export, or --info, so an agent can pose one part of an assembly. The triangle limit applies to the parts shown, so a project too large to draw whole can be seen part by part.
3MF: the core specification’s meshes, components, and build transforms; colors from base materials and color groups; objects kept in separate parts of the package, as slicers write them. Projects from Bambu Studio and its relatives are drawn in their filament colors, which those programs keep in settings of their own; colors painted onto faces are not read. Textures, beam lattices, slices, and encrypted content are not read. The same 932,067-face limit applies: a larger model is shown by its embedded thumbnail, and described by i. A package may hold 4,096 entries and unpack to 128 MiB; one that unpacks to more is shown by its thumbnail too, and described by what its root model says.
Plain text (.txt, .text, .log, and any file that is not binary): shown as it is, in the document view, so that no line of it is read as a heading, a list, or emphasis. Returns and a byte order mark are dropped, bytes that are not UTF-8 stand as �, and a file longer than 2 MiB is cut. A file of no known kind is read as text when its first 8 KiB hold no NUL byte, are UTF-8, and are mostly printable, as less would show it; source code and configuration open that way, highlighted by chroma in the language its name or first line says. Only binary files are unsupported.
JSON (.json, .jsonl, .ndjson): pretty-printed and highlighted as a fenced block; s shows it as it is in the file. A file with one value to a line, such as a training set, a batch request, or a log export, is shown as numbered records, whatever its name. Malformed JSON is refused with the line it fails on. Extensionless JSON and stdin are recognised by parsing. The view is cut at 2 MiB of pretty-printed text; i says how many records there are.
Jupyter notebooks (.ipynb, nbformat 4): Markdown cells as they are, code cells fenced in the kernel’s language after their In [n] count, and each output after its cell: text as it was printed, errors without their colour codes, and PNG, JPEG, GIF, and SVG outputs as pictures. Widgets, HTML, and LaTeX outputs fall back to their text.
HTML (.html, .htm): converted to Markdown with html-to-markdown, so saved pages and wiki exports read as documents: headings, lists, tables, links, code, and pictures beside the file are kept; scripts, styles, and layout are not. Nothing is fetched. A page may be 8 MiB.
Word (.docx, .docm): turned into Markdown and shown as such, so s shows the Markdown. Headings, lists, tables, links, pictures, and bold, italic, and struck text are kept; page layout, headers and footers, footnotes, comments, and text boxes are not. A document longer than 2 MiB of Markdown is cut.
Excel (.xlsx, .xlsm): each sheet is a grid that scrolls by row and column, with n and p turning between sheets. Cells show their values, formulas by their last result, and dates and times where a cell’s style says so. Up to 100,000 rows and 1,024 columns of a sheet are read; the rest are counted. Formatting, merged cells, charts, and pictures are not shown.
Grist (.grist): a Grist document is a SQLite database, and each of its tables is shown as a sheet is, with n and p turning between tables. The first row holds the columns’ labels, and rows and columns stand in the order Grist keeps them in; summary tables come after the others, titled as Grist titles them (Sightings [by Site]), what they group by shown as the table summed shows it. Cells show what is stored: formulas by their last result, as Grist saved it, and an error by its name (#TypeError). Dates and times are written out, a reference shows what Grist shows for it, or Table[row] where it shows the row, lists are joined with commas, and attachments are named, not opened. A hyperlink cell shows its words and leads to its address, as an Excel link does. Row ids, the positions rows are sorted by, Grist’s helper columns, and a summary’s list of the rows behind each line are left out. Nothing is worked out anew: no formulas, access rules, widgets, or number formats, and nothing is written. Up to 100,000 rows and 1,024 columns of a table are read. A document in SQLite’s WAL mode is not read, nor is any other SQLite database: gloss is not a database browser.
CSV (.csv, .tsv): shown as a sheet is. The separator is read from the file: a comma, tab, semicolon, or pipe, whichever the first lines agree on; a .tsv is read as tabs. Quoted values may hold the separator and line breaks. Only the file’s name says it is a table: text is not sniffed.
Columns of a table: x hides the one under the cursor, X brings them all back, and c lists them to tick and untick. Hidden columns keep their letters, and one column always stays. --cols Name,City shows only the columns with those headers (or letters), and --coln 2,4-6 those numbered so, in every table opened; a table with none of them is shown whole.
Web addresses in tables: a cell that holds an address or, in Excel and Grist, links to one is marked 🔗, and is a link to the terminal as well: click it as your terminal has links clicked (often with Cmd, Ctrl, or Shift held, since gloss takes plain clicks) and the terminal opens it in your browser. gloss itself starts no browser. A sheet has a cursor, and the status bar shows the address under it. With --fetch, Enter on such a cell downloads what it names and opens it like a dropped file; a picture is shown as one, and Esc closes it and returns to the cell. Only http and https are fetched, of no more than 128 MiB, and only on Enter or a URL drop/paste: gloss never fetches on its own. Fetched files are removed when closed or when gloss exits, unless they were picked.
Input files and stdin are limited to 128 MiB. One active document and, when enabled, one independent preview are kept open. Images, SVGs, and PDF pages zoom by cropping the existing raster, up to 64×; use a higher PDF DPI for more detail. There is no file watching, and no fetching unless --fetch is given; even then only Enter on a cell or an explicit URL drop/paste fetches.

Development

Mon, 01 Jan 0001 00:00:00 +0000

Development#

gloss is written in Go on Bubble Tea and NTCharts, with NTCharts SVG, NTCharts PDF, and NTCharts3d. The user documentation is on the documentation site; this file is for working on gloss itself. AGENTS.md is the same ground for coding agents.

Build and run#

Requires Go 1.26.8+ and Task for the development commands. Without Task, build with go build -o gloss ./cmd/gloss. Go’s automatic toolchain selection can download that version. Dependencies are pinned in go.mod; sibling checkouts aren’t needed. Clone with --recurse-submodules (or run git submodule update --init) to get the documentation theme.

For LLMs

Mon, 01 Jan 0001 00:00:00 +0000

For LLMs#

This is the skill gloss carries for agents. The binary prints it with gloss skill, and gloss skill install puts it where the agents on a machine look, so it always matches the flags that binary has.

“Inspect local files with gloss: extract document text and tables, export images, PDF pages, SVG, and meshes as PNGs for vision, read metadata, or ask a human to choose or view files. Use for file inspection and local file handoffs, not document creation or editing.”