#Getting started with SugarCraft
Three ways to get something on your screen in about five minutes — run a finished binary, scaffold an app, or taste one library. Then a router table for "I want to X, which package is that?", and the install-path truth stated once. New to the vocabulary? docs/GLOSSARY.md defines every term below.
Before you install —
sugarcraft/*packages publish fromdev-masteruntil their first tags are cut, so a Composer project left on the defaultstableminimum-stability cannot resolve them. Add"minimum-stability": "dev", "prefer-stable": trueto your rootcomposer.json(or suffix your require with@dev).
#Route A — run a finished app (no Composer needed)
Signed single-file phars ship on the releases
page. Every release carries a
SHA-256 sidecar; candy-code/candy-top builds from v0.1.1/v0.1.0
onward also carry an Ed25519 minisig verified against the pinned key
(SECURITY.md). Requirements: PHP 8.3+.
curl -LO https://github.com/detain/sugarcraft/releases/download/candy-code/v0.1.1/candy-code.phar
curl -LO https://github.com/detain/sugarcraft/releases/download/candy-code/v0.1.1/candy-code.phar.sha256
sha256sum -c candy-code.phar.sha256
php candy-code.phar doctor # checks your PHP extensions, then:
php candy-code.phar # the AI coding-agent TUI
curl -LO https://github.com/detain/sugarcraft/releases/download/candy-top/v0.1.0/candy-top.phar
curl -LO https://github.com/detain/sugarcraft/releases/download/candy-top/v0.1.0/candy-top.phar.sha256
sha256sum -c candy-top.phar.sha256
php candy-top.phar # the btop-style system monitor
A tagged phar updates itself: php candy-top.phar self-update --check, then
self-update (and --rollback once if you ever want the previous file
back). candy-code/v0.1.0 predates the signing key — install v0.1.1
instead; see candy-code/README.md for the
full story.
#Route B — build your first TUI
The starter is the shortest path to a running program: bin/start hands a
Model to sugar-core's Program, which owns the event loop, raw mode, and the
alt-screen. You only write the Model.
composer create-project sugarcraft/candy-starter my-app --stability=dev
cd my-app
./bin/start # a counter demo; q / Esc / Ctrl+C quits
A Model is the four-method contract — this compiles as-is:
<?php
declare(strict_types=1);
namespace App;
use SugarCraft\Core\{Model, Msg, Subscriptions};
final class Greeter implements Model
{
public function init(): ?\Closure { return null; }
/** @return array{0: Model, 1: ?\Closure} */
public function update(Msg $msg): array { return [$this, null]; }
public function view(): string { return 'hello'; }
public function subscriptions(): ?Subscriptions { return null; }
}
Keys arrive as Msgs, timers and streams ride subscriptions(), and every
effect is a Cmd closure — GLOSSARY.md and the sugar-core
README walk each one.
#Route C — taste one library
Charts are the smallest full dependency: add sugar-charts to any project and one class gives you a block-element sparkline on stdout.
composer require sugarcraft/sugar-charts
<?php
require __DIR__ . '/vendor/autoload.php';
use SugarCraft\Charts\Sparkline\Sparkline;
echo Sparkline::new([1, 3, 2, 8, 5, 4, 7, 6], 8)->view();
// ▂▁█▅▃▇▆
#I want to … → which package?
| Goal | Reach for |
|---|---|
| Run an AI coding agent in the terminal | candy-code |
| Monitor CPU/memory/disks/network like btop | candy-top |
| View an image in the terminal | candy-image (CLI) / sugar-image (library) |
Play a GIF or .ansi art file |
candy-gifview |
| Browse/edit files | candy-files |
| Query databases | candy-sql |
| Drive git with keys | candy-git |
| Read markdown in the terminal | candy-mdview |
| Start your own app | candy-starter + sugar-core |
| Sparklines, bars, line charts | sugar-charts |
| Forms and fields | sugar-forms |
| Sortable/filterable tables | sugar-table |
| Parse raw terminal byte-streams | sugar-ansi-parser / sugar-input |
| Sprites, physics, animation | sugar-spring, sugar-animation |
| Record/replay a TUI session in tests | candy-vcr, sugar-testing |
The full matrix with upstream comparisons is docs/MATCHUPS.md; the site mirror is sugarcraft.github.io.
#Why PHP?
Because one language can cover the whole stack: the same final class that
computes your business logic also returns the exact SGR bytes that paint it,
with no daemon, FFI boundary, or second runtime between the two. Packages
stay composer-installable like any other PHP library, and finished apps
still ship to people who never touch Composer — as one signed, self-updating
.phar file (Route A). PHP 8.3's strict types plus ReactPHP cover the async
event loop the interactive stack runs on.
#The binary-path truth (once, for everything below)
Depending on how you got a package, its launcher lives in one of four
places — READMEs use vendor/bin/… and ./bin/… for different ones:
- You
composer required it into your project → the command isvendor/bin/candy-code(anycandy-*package with a binary). - You are inside a checkout of the package itself (monorepo or clone) →
it is
./bin/candy-code, novendor/prefix. - You are a release user → there is no bin at all:
php candy-code.phar. - You want it globally →
composer global require sugarcraft/candy-codeand put~/.config/composer/vendor/binon yourPATH.
#Accessibility & reduced motion
REDUCE_MOTION/PREFERS_REDUCED_MOTION— either variable reading on (anything except empty,0,false,no,off, case-insensitively) is read bySugarCraft\ColorProfile\Probe::reducedMotion()and honored bysugar-spring: spring-composed types snap straight to their target instead of animating (projectiles and easing curves are gate-yourself app-side; see the sugar-spring README).NO_COLOR: color depth is detected fleet-wide bysugar-core'sColorProfile::detect()(TERM /COLORTERM/NO_COLOR/ CI probes) and announced to every program as aColorProfileMsg; the full precedence ladder is documented in the sugar-colorprofile README. Applying it is app-by-app: sugar-style renderers honor the profile, while some apps pick their depth from their own config first — candy-top, for example, derives it from itstruecolor/terminal-mode options and does not consume the startup message. If an app ignoresNO_COLOR, that is a bug worth a report.- Keyboard-only operation and per-app key tables are indexed in docs/KEYMAPS.md.
#Where to read more
- docs/GLOSSARY.md — every term, defined with its source file.
- docs/KEYMAPS.md — fleet keymap index (pointers).
- sugar-core README — the runtime, plus the shared environment-variable table.
- docs/TRUST-BOUNDARY.md — what untrusted input may and may not do; read before rendering anything you didn't author.
- SECURITY.md — releases, signing, supported versions.
- candy-code/docs/TROUBLESHOOTING.md — the flagship app's failure-mode guide.
- CONTRIBUTING.md + AGENTS.md —
conventions, the per-lib
composer install && vendor/bin/phpunitloop, and how path repositories work.