> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MonoGlyph

> Render PNG and JPEG images as terminal glyphs, Braille, true-color blocks, vector halftones, structural ASCII, or animated HTML.

MonoGlyph converts pixels into a field of characters, dots, lines, planes, or
edge-aware glyphs. It can print a terminal preview, emit plain text, produce a
scalable SVG asset, or build a self-contained animated HTML canvas.

*Current public CDN contract: `monoglyph 0.3.0`, OpenCLIs build
`2026-07-12-153753`.*

<Info>
  The OpenCLIs installed-state row, shell-resolved binary, and public CDN now
  agree on `monoglyph 0.3.0`, build `2026-07-12-153753`. A developer checkout can
  currently report source version `0.4.0` with unreleased `screentone`, ordered
  dithering, ring/polarity controls, and animation presets. Those source-ahead
  features are not in `latest.json`; portable/public workflows must use the
  `0.3.0` contract documented here.
</Info>

The public payload has **14 rendering modes** and **four output targets**. The
supported-combination matrix matters: 14 × 4 does not mean every one of the 56
pairs is valid.

## Quick Start

```bash theme={null}
openclis install monoglyph

monoglyph --version
monoglyph photo.jpg --mode glyph --cols 120
monoglyph photo.jpg --mode dots --target svg --color -o photo.svg
```

MonoGlyph accepts a PNG or JPEG path as its single positional input.

## Complete Option Reference

| Option                       | Values or behavior                                                                                                |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `--mode <mode>`              | Selects the rendering primitive. The complete published mode table is below. Default: `glyph`.                    |
| `--target <target>`          | `ansi`, `text`, `svg`, or `html`. Default: `ansi`. Not every mode supports every target.                          |
| `--cols <n>`                 | Sets output width in character cells; default 100. Height preserves image aspect using terminal-cell proportions. |
| `--color`, `--colour`        | Uses source-image colors where the selected mode supports them.                                                   |
| `--invert`                   | Makes light pixels produce more ink instead of dark pixels.                                                       |
| `--dither`                   | Applies Floyd–Steinberg error diffusion in glyph mode.                                                            |
| `--fg <hex>`                 | Overrides monochrome ink color.                                                                                   |
| `--bg <hex>`                 | Sets SVG/HTML background color.                                                                                   |
| `--charset <set>`            | Uses `ramp`, `binary`, `blocks`, or a literal darkest-last character sequence.                                    |
| `-o`, `--out <file>`         | Writes the rendered artifact to a file instead of stdout.                                                         |
| `-h`, `--help`               | Prints the installed command reference.                                                                           |
| `version`, `--version`, `-V` | Prints the executing binary's version.                                                                            |

## Published Rendering Modes

| Family     | Modes                                      | Intended form                                                         |
| ---------- | ------------------------------------------ | --------------------------------------------------------------------- |
| Characters | `glyph`                                    | Density-selected ASCII/Unicode characters                             |
| Dots       | `dots`, `halftone45`, `stipple`, `braille` | Halftone, randomized stipple, or 2×4 Braille detail                   |
| Lines      | `scanlines`, `wave`, `flow`, `crosshatch`  | Bands, ridges, gradients, and pen hatching                            |
| Planes     | `cells`, `quadtree`, `blocks`              | Mosaic, adaptive subdivision, or true-color half-block terminal image |
| Structure  | `structure`, `match`                       | Edge-tangent glyphs or CodexMono patch-shape matching                 |

## Valid Target Combinations

| Modes                                                                                           | Targets         |
| ----------------------------------------------------------------------------------------------- | --------------- |
| `glyph`, `structure`, `match`                                                                   | ANSI, text, SVG |
| `glyph`, `dots`                                                                                 | Animated HTML   |
| `braille`                                                                                       | ANSI, text      |
| `blocks`                                                                                        | ANSI            |
| `dots`, `halftone45`, `stipple`, `scanlines`, `wave`, `flow`, `crosshatch`, `cells`, `quadtree` | SVG             |

`--color` is available across the published combinations except the continuous
indigo `wave` and `crosshatch` modes. An unsupported mode/target pair is a
contract error, not an automatic format substitution.

## Published Platforms

| Target          | Artifact |
| --------------- | -------: |
| macOS Arm64     |      Yes |
| Linux x86\_64   |      Yes |
| Linux Arm64     |      Yes |
| Windows x86\_64 |      Yes |
| Windows Arm64   |      Yes |
| Intel macOS     |       No |

Both Windows packages include `monoglyph.exe`. The release is a single-run
converter with no daemon or database on every platform.

## Workflow Handoffs

```text theme={null}
web page ── MonoSurf screenshot ──┐
                                  ├── image file ── MonoGlyph ── terminal/text/SVG/HTML
desktop ── Kernel CLI capture ────┘
```

| Tool                          | Boundary                                                                                             |
| ----------------------------- | ---------------------------------------------------------------------------------------------------- |
| [MonoSurf](/monosurf/index)   | Captures a web page through CDP; MonoGlyph begins only after an image file exists.                   |
| [Kernel CLI](/kernel-cli)     | Captures the desktop, display, window, or region; MonoGlyph owns conversion, not OS consent/capture. |
| [CodexMono](/codexmono/cli)   | Intended cell font for alignment-sensitive glyph output.                                             |
| [Monogrid](/ai-clis/monogrid) | Verifies textual box geometry; it does not validate raster, SVG, or HTML image fidelity.             |

MonoGlyph does not maintain an index or background service. Its persistent
effects are limited to the path supplied with `--out` or an explicit shell
redirection.