All 22 apps

CandyImage

Terminal image viewer CLI

chafa CLI surface idea (hpjansson/chafa), not a port image sixel kitty iterm2 cli

CandyImage code coverage

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

One-command viewercandy-image file.png — protocol auto-detection (kitty → iterm2 → sixel → shell-out-free text floors) behind a single flag surface.
--dump-detectchafa's debugging gold re-expressed over the native stack: env table, TermDb chain + claims, probe capabilities, cell pixels, default fg/bg, DA1 reply, and the resolved auto() choice.
Cell sizing--size=WxH / --width / --height / --scale=fit|shrink|fill|stretch|none|crop, mapped straight onto sugar-image's Scale enum.
Never shells out--format=chafa is refused by design — this viewer exists precisely to retire the chafa dependency from the image path.
Honest flagschafa spellings with no PHP backing here (--format=chafa, --passthrough=tmux / screen) exit 1 naming what is missing — no silent ignore; --polite is a documented no-op.
Testable coreAll argument handling lives in 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.
Exit-code contract0 success, 1 usage error, 2 input/decode failure — pinned in the suite so scripts can branch on it.

Source & demos

Try the quickstart →

API

ClassMethodDescription
Climain(argv, stdout, stderr, play)Parse args, detect, render or animate; returns the exit code
CliviewportCells()TTY-sized cell box (cols, rows-1) behind a stream_isatty gate, 60×24 fallback
ClirunningVersion()Effective version string: the phar build stamp when running from a packaged phar, else the VERSION constant
CliworkDialToFactor(dial)chafa's integer --work dial (1–9) mapped onto the sugar-image float factor (N−1)/8; null when unmapped
Langt(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

Viewer

A synthetic PNG through the real CLI path, then --dump-detect walking the protocol ladder to answer "why is my image blank?".