gloss

Install

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

Install#

With Homebrew, on macOS or Linux:

brew install --cask nimbleterminal/tap/gloss

The Homebrew installation note includes gloss skill install for AI agents, and two tools for video, which gloss needs only for that: mpv, whose library plays videos in the viewer, and FFmpeg, whose ffprobe and ffmpeg describe them and draw their frames for previews, thumbnails and exports. Without mpv a video does not play; without FFmpeg it plays, without details or a still. On Debian or Ubuntu, install the libmpv2 (or mpv) and ffmpeg packages; on Windows, put libmpv-2.dll and FFmpeg on your PATH.

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. An http:// or https:// address in place of a file is downloaded first, then shown like the file it is; see Opening a web address.

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 graphics 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 (including the build version) / dismiss help
`f` in typeset text	Preview font pairs: arrows select, Enter keeps, Esc restores; `+`/`-` still zoom
`T` over a document	Preview themes: arrows select, Enter keeps, Esc restores
`F2` over a document	Preview languages: arrows select, Enter keeps, Esc, `q` or `F2` restores. System follows the locale
`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
`?` with an empty browser filter, or `F1`	Show file-browser help; Esc/F1 returns to the same filter and selection
`w`, `W`, `E`; Alt+Enter in the browser	Open with the default app / choose an app / edit with the default editor; Alt+Enter opens the chooser on Open with. In the chooser Tab switches Open with and Edit with, `d` saves the default for that kind and verb, `m` manages apps (Space toggles, Enter/Esc returns)
`]` / `[`	Next / previous file. `Tab` / `Shift-Tab` do the same, except in rendered Markdown, where they move between pictures, links and tables
`a`, `Shift-F10`; right-click	Actions for the picture, video, link, table or spreadsheet cell under the pointer or highlighted
`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
`t` on Markdown, text, source or JSON	Toggle normal text / typeset view
`t` on an HTML page	Toggle its text / the page as its CSS lays it out
`/` in typeset mode	Open the text/source view and search
`s` in typeset mode	Toggle the typeset view and text/source
`#`	Show or hide file line numbers, in text and typeset views of plain text, source, JSON and Markdown source
`:`	Go to a line: type its number, `Enter` goes there, `Esc` cancels; a number past the end goes to the last line
`S`	Chop long lines at the right edge instead of wrapping them, as `less -S` does, and back; chopped, `←`/`→` and `h`/`l` scroll sideways and `Home` returns to the left edge
`Home` / `End`, `G`	First / last PDF page
Arrows, `h j k l`	Move about a spreadsheet by row and column
Click a cell	Select it in a spreadsheet; a row number keeps the column, a column letter the row; a second click on a cell with an address opens it, as `Enter` does
`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, or a table opened in gloss, and return to where you were
`+`, `-`	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, OBJ, PLY) orbit / pan / zoom
Arrows or `hjkl`, `+`/`-`, drag, wheel	Map (GeoJSON, GPX, PMTiles): pan, zoom; `f` or `0` frames the whole file again
`/`	Map: find a place by name and center on it, with `--fetch` and a provider named in `GLOSS_GEOCODER` (see Online maps)
Drag, then `y`	Typeset text: select, then copy to the clipboard; `Esc` clears
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 fetches only an http(s) address you name on the command line, or one you choose inside a document with –fetch; GLOSS_NO_FETCH in the environment forbids both.

Option	Argument	Default	Description
`--strict`			require OS confinement for supported document loads (still images, SVG, Mermaid, PDF)
`-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
`--theme`	`string`	`"auto"`	Colors: auto, catppuccin-latte, catppuccin-mocha, dark, dracula, gruvbox-dark, gruvbox-light, light, monokai, nord, one-dark, rose-pine, solarized-dark, solarized-light, tokyo-night, or theme JSON file
`--lang`	`string`		language of gloss’s own words and number formats (BCP 47 or POSIX, e.g. es, zh-Hans, de_DE); options stay English
`-X`, `--no-alt-screen`			draw on the main screen: scrollback is kept, and the last view stays after quitting
`--print`			print one content viewport to stdout and exit; pictures use ANSI-colored half-blocks, no terminal required
`--print-width`	`int`		with –print, viewport columns (1–512; default terminal width or 80)
`--print-height`	`int`		with –print, viewport rows (1–256; default terminal height or 24)
`--qr`	`string`		show this text, such as a URL, as a QR code instead of a file, to scan with a phone or tablet; with –serve, on a web page; nothing is fetched
`-t`, `--type`	`string`		force input type: image, svg, pdf, stl, 3mf, obj, ply, docx, xlsx, grist, csv, json (or jsonl, ndjson), ipynb, html, text, markdown (or md), mermaid, video, geojson, gpx, pmtiles
`--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, and the map provider named in GLOSS_MAP_TILES and GLOSS_GEOCODER; an address named on the command line needs no option, and GLOSS_NO_FETCH forbids both
`--user-agent`	`string`		what downloads send as their User-Agent; else $GLOSS_USER_AGENT, else gloss and its version

Examples#

# Print one view into captured shell output
gloss --print --print-width 80 photo.png

# Hand a link to a phone: show it as a QR code on a web page
gloss --serve --qr https://example.com/

# 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, typesetting text, 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)
`--markdown`	`string`	`"text"`	Markdown renderer: text, typeset (direct graphics)
`--typeset`			Typeset Markdown, HTML, plain text, source code, and JSON as graphics
`--font`	`string`	`"readable"`	Typeset font pair: readable, editorial, technical, compact
`--mono`	`string`		Override typeset code face: jetbrains
`-N`, `--line-numbers`			number the lines of plain text, source code, JSON and Markdown source (# toggles, : goes to a line)
`-S`, `--chop-long-lines`			cut long lines at the right edge instead of wrapping them, as less -S does (S toggles, arrows scroll sideways)
`--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, 3MF, OBJ and PLY

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

Meshes: STL, 3MF, OBJ and PLY#

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: 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
`--up`	`string`		the axis a mesh file treats as up: y or z; STL defaults to z, OBJ and PLY to y
`--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

# An OBJ exported Z-up, stood upright
gloss --up z model.obj

# 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

Videos

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

Videos#

Frames of a video for a model to look at, drawn by ffmpeg without playing it: at the times named, or a number spread through it, as one labelled sheet or a file each. With --json each frame comes with its time and the subtitle shown then. --text gives a video’s subtitles, with their times: an SRT or WebVTT file named after it beside it, or its own text subtitles.

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.

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.

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.

Steering a running viewer

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

Steering a running viewer#

A viewer started with --socket NAME answers other programs on a Unix socket, gloss-NAME.sock in the temporary folder (or at the path given). gloss --remote NAME FILE opens the file in that viewer, whatever it is doing: help, a search, a picker or the file browser gets out of the way. With --reload the viewer loads its file again, with --quit it ends, and with nothing it prints the file it shows; --json gives the viewer’s whole answer. The socket is the user’s alone, and the viewer treats what arrives as paths to probe, as it does a drop. On Unix, SIGUSR1 reloads too. An editor or terminal multiplexer keeps one gloss pane and points it at each file in turn.

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 help; gloss skill show prints the skill; gloss skill install, or gloss skill install agent, writes it where the agents on this machine look, or into the skills folder named. gloss skill install rex writes the Lua that joins gloss to the Rex terminal multiplexer into Rex’s config folder: the gloss_companion action (cmd+shift+g), a gloss split that follows the shell and editor beside it over --socket, and gloss_push; it adds require("gloss") to init.lua once and has Rex reload.

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.

Steering a running viewer

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

Steering a running viewer#

A gloss that is already open can be told what to show by another program on the same machine: an editor, a terminal multiplexer that keeps a preview pane, a build script, or another gloss. Start the viewer with a socket name, and point it at files from anywhere:

gloss --socket preview README.md # in one pane: a viewer that takes requests
gloss --remote preview notes.pdf --page 3 # from another: show this, on page 3
gloss --remote preview --reload # the file was rewritten: load it again
gloss --remote preview # which file is it showing? (prints its path)
gloss --remote preview --quit # close it

--socket NAME makes the viewer listen on a Unix domain socket, gloss-NAME.sock in the temporary folder ($TMPDIR, or /tmp); a name with a slash in it is used as the socket’s path. A name is letters, digits, dots, dashes and underscores. The socket is readable by your user alone, and a stale one left by a viewer that crashed is replaced; a name another viewer is still listening on is an error.

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. README HTML images (<img src="…">), including <a> links inside <p> or <div>, use the same local-image and GIF playback path as Markdown images. Relative paths resolve beside the Markdown file. Numeric width and height (1–4096 pixels) bound the image without stretching; align="left|center|right" on the image or wrapper positions it. Terminal text rounds sizes to cells and retains its inline-image height limit. CSS, event handlers, srcset, scripts, and remote/data images are not enabled. This is an image subset, not general HTML layout; source view retains the markup.

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 on this machine (gloss skill install agent)
gloss skill install agent ~/.claude/skills # or into the skills folder named
gloss skill show # print it, to place it by hand

Installation always writes the shared ~/.agents/skills folder, which Codex and other agents read but do not create, and the folder of each agent found by its home: Claude Code (~/.claude/skills) and Kimi Code (~/.kimi-code/skills, or $KIMI_CODE_HOME). It reports each agent and skill path once in the terminal. Redirected stdout contains just the installed paths, one per line, for scripts; progress messages go to stderr.

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. AVIF isn’t supported.
GIF and animated WebP: 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 and animation to 1,000 frames. A GIF’s indexed frames are decoded up front, within 64 Mi frame pixels in total, checked before decoding. A WebP’s frames stay compressed and are decoded as they are shown, so a long full-canvas clip costs its canvas and one frame, not every frame; a large lossy frame can take longer to decode than its delay, in which case playback runs slower rather than skipping. A WebP frame that fails to decode is skipped. Alpha, blend and dispose-to-background settings are honored. 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, notebook images, and headless --output use the first frame on the full logical canvas. Frames are not --pages. Embedded Markdown GIFs and WebPs animate when visible: at most eight distinct destinations and 64 MiB of animation storage per document (decoded GIF frames; a WebP’s canvas plus its retained compressed container); excess animations remain still.
Video: MP4, M4V, MOV, WebM, MKV, Ogg (.ogv, Theora), AVI, MPEG, WMV and FLV, by name or by their first bytes (Ogg audio is not a video). The viewer plays them through mpv’s library, found when a video is opened (brew install mpv or your system’s mpv package); it opens paused on the first frame. Details (i, --info) come from ffprobe, and the first frame, for previews, thumbnails, --output and --print, from ffmpeg, both from FFmpeg. Without mpv a video does not play and says so; without FFmpeg it plays but has no details or first frame. A video is never read into gloss: it may be up to 2 GiB and 4096×4096, from a local file only, not a URL. In the browser demo and app, a video plays in the browser’s own video player, laid over gloss’s cells, with the same keys: whatever the browser can decode, within the app’s 128 MiB file limit. There it has no details, preview or thumbnail, which come from FFmpeg. Subtitles: files beside a video and named after it (clip.srt, clip.en.srt, clip.vtt, clip.fr.ass), up to 16 of 2 MiB each, the one with no language first, then by name; and the video’s own subtitle streams. mpv draws them into the picture; drawn with glyphs, where they could not be read, they are terminal text over it instead. In the browser, SRT is converted to WebVTT and ASS/SSA are left out. --text prints a video’s subtitles with their times: the first SRT or WebVTT file beside it, else its own text subtitles (FFmpeg); --info lists those. --at and --frames export frames at chosen times; see Frames of a video.
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.
JPEG XL: the first frame of a bare codestream or a .jxl container, lossless or lossy, up to 32 megapixels, oriented as the file asks. Uses the pure-Go jxl decoder, without CGO or external converters; embedded ICC profiles are not applied, and animated files show their first frame. Exif in the container feeds the info box. JPEG XL works in Markdown, previews, PNG exports, and the browser demo.
SVG: ntsvg’s pure-Go SVG renderer, rasterized to a 2400-pixel maximum edge. SVG support follows the underlying oksvg renderer, not a full browser engine. Rendering runs in an isolated worker that is stopped after 15 seconds.
Mermaid: a .mmd or .mermaid file is one diagram, drawn as Markdown’s mermaid fences are (see Markdown), in the theme’s light or dark palette, and shown like a picture. Recognized by name only: the same text in a .txt file stays text. The source is limited to 64 KiB. --text gives the source; a diagram that does not parse is an error that names the line.
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. Decoded streams are limited to 256 MiB per decoding stage and 1 GiB of total decoding work. Stream lengths, chained filters, and predictor buffers are checked before opening. Ambiguous lengths, indirect filters/decode parameters, and unbudgeted filters (including LZW, JPEG 2000, and JBIG2) are rejected. PDF metadata and text parsing run in isolated workers with a 15-second deadline; timed-out workers are stopped. / 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: nt3d’s mesh limit. Normals are recomputed from vertex winding; binary STL face colors using the VisCAM/SolidView or Materialise Magics convention are honored. 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, OBJ or PLY 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.
OBJ: Wavefront OBJ triangles and polygons (concave ones split), polylines, vertex colors, the diffuse colors (Kd) of the materials its .mtl libraries give, and their PNG or JPEG textures (map_Kd), repeating as OBJ textures do. Side files are read only from beside the model or a folder below it, never for standard input: at most 32, libraries of up to 1 MiB, textures of up to 16 MiB and 16 megapixels each, 64 megapixels together. A texture that is refused or cannot be read leaves its faces in the material’s color, and i says why. Textured faces keep their texture when the mesh is painted with C. Faces with their own normals are smooth-shaded. The same 932,067-face limit applies.
PLY: Stanford PLY, ASCII or binary: faces with vertex or face colors, a scanner’s range grid joined into a surface, or, with no faces, a cloud of up to 500,000 points drawn as discs sized to the spacing of their neighbors. A texture the file names is not read.
OBJ and PLY files do not say which way is up; gloss takes Y as up, as most tools write them, and turns them to the Z-up that STL, 3MF and the named views (--view top) use. A model that comes out lying on its side was written the other way: --up z reads an OBJ or PLY as Z-up, and --up y stands up a Y-up STL. i says which axis was taken. 3MF is Z-up by its specification.
GeoJSON (.geojson) and GPX (.gpx, or any file whose root element is <gpx>): what the file holds is drawn on a plain background, framed to fit, and nothing is fetched. Points and GPX waypoints are pins, lines, routes and track segments are lines (one per segment), and polygons are drawn as thinner outlines, holes included. GeoJSON is known only by its name, so a .json file stays JSON; --type geojson reads one as a map. A file may hold up to a million positions and 100,000 features, nested at most 64 deep; elevation, times and other properties are not read. A file with no positions in it is an error.
PMTiles (.pmtiles, or a file that begins as one): an archive of map tiles, shown as a map you can pan and zoom, framed on the bounds it declares. It is not read whole, as other files are: its tiles are read from the file as the map needs them, so the 128 MiB limit does not apply (except to a downloaded or piped archive). Only raster archives, of PNG or JPEG tiles, with uncompressed or gzip directories, can be drawn; a vector (MVT) archive is described and refused. Each read is bounded: a directory or the metadata at most 16 MiB, a tile at most 8 MiB and 4096 pixels a side. The archive’s attribution is drawn along the map’s foot.

Online maps#

gloss has no map service of its own: it never asks one for anything unless you name it. In the viewer, with --fetch, these settings in the environment add one:

Development

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

Development#

gloss is written in Go on Bubble Tea with ntpicture, ntsvg, ntpdf, and nt3d. 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.

Go module path#

The root module is nimbleterminal.dev/gloss. Self-imports and the separate examples/demo module uses that prefix; its local replacement still points at the root checkout. GitHub remains the source host. Consumers moving from the GitHub module path must update their imports and use a version published after the migration. Existing tags are unchanged.

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.”