CandyImage
Terminal image viewer CLI
The chafa-independent terminal image viewer: point candy-image at a PNG, JPEG, GIF or static WebP (BMP and other GD-decodable formats ride the getimagesize() fallback) and it detects your terminal, picks the best protocol — sixel, kitty, iTerm2, half/quarter blocks, an ANSI character ramp, or the chafa symbol engine — and writes the rendered bytes to stdout. All capability stays in sugar-image; this app is composition only.
Install
composer require sugarcraft/candy-image
Requires PHP 8.3+ and the gd extension — every render path decodes through it. The hard requirement reaches composer consumers transitively through sugar-image; a downloaded phar carries no platform check at all, so that sentence is the guardrail. Packagist serves dev-master only (no tag yet), so under default stability ask for the dev package explicitly: composer require "sugarcraft/candy-image:@dev".
Quickstart
candy-image photo.png # auto-detect + render
candy-image --format=half --size=80x24 logo.png
candy-image --dump-detect # why is my image blank?
candy-image --animate clip.gif # sugar-animation playback
What's in the box
candy-image file.png — protocol auto-detection (kitty → iterm2 → sixel → shell-out-free text floors) behind a single flag surface.--size=WxH / --width / --height / --scale=fit|shrink|fill|stretch|none|crop, mapped straight onto sugar-image's Scale enum.--format=chafa is refused by design — this viewer exists precisely to retire the chafa dependency from the image path.--format=chafa, --passthrough=tmux / screen) exit 1 naming what is missing — no silent ignore; --polite is a documented no-op.SugarCraft\CandyImage\Cli — the bin is a thin shim by design (an autoload probe with phar-identity resolution, then a one-line Cli::main() hand-off), and a closure seam lets tests drive the wired Player without a terminal.Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Detection + render engine: sugarcraft/sugar-image; animation playback: sugarcraft/sugar-animation.
- The CLI surface was sparked by chafa (C); SugarCraft is a native PHP project — this is a composition-only viewer, not a port.
API
| Class | Method | Description |
|---|---|---|
| Cli | main(argv, stdout, stderr, play) | Parse args, detect, render or animate; returns the exit code |
| Cli | viewportCells() | TTY-sized cell box (cols, rows-1) behind a stream_isatty gate, 60×24 fallback |
| Cli | runningVersion() | Effective version string: the phar build stamp when running from a packaged phar, else the VERSION constant |
| Cli | workDialToFactor(dial) | chafa's integer --work dial (1–9) mapped onto the sugar-image float factor (N−1)/8; null when unmapped |
| Lang | t(key, params) | Localized CLI messages (namespace image) |
Demos.
VHS-recorded GIF of the viewer CLI end to end, regenerated automatically on every push that touches the source.
Viewer
A synthetic PNG through the real CLI path, then--dump-detect walking the protocol ladder to answer "why is my image blank?".