CandyScriptui
Composer-installable CLI of TUI primitives
13 presentation subcommands — choose, confirm, file, filter, format, input, join, log, pager, spin, style, table, write — plus completion and version utilities. Drop into a shell script and instantly get a Charm-quality interactive UX.
Install
composer require sugarcraft/candy-scriptui
Or grab the rolling latest phar — rebuilt and published for every commit that
touches this app (verify against the published .phar.sha256 sidecar
before making it executable):
curl -fsSLO https://github.com/detain/sugarcraft/releases/download/candy-scriptui/latest/candy-scriptui.phar
curl -fsSLO https://github.com/detain/sugarcraft/releases/download/candy-scriptui/latest/candy-scriptui.phar.sha256
sha256sum -c candy-scriptui.phar.sha256 && chmod +x candy-scriptui.phar
Quickstart
# Apply styling.
candy-scriptui style --foreground "#ff5f87" --bold "Hello, candy!"
# Pick one item.
choice=$(candy-scriptui choose Pizza Burger Salad)
# Read a single line.
name=$(candy-scriptui input --placeholder "Your name?")
# Confirm a destructive action.
file=old-build.log
candy-scriptui confirm "Really delete $file?" && rm "$file"
# Show a spinner while running a command.
candy-scriptui spin --title "Building..." -- make build
# Filter a list (substring by default; --fuzzy for fuzzy matching).
git branch | candy-scriptui filter
What's in the box
Keyboard & color
Every interactive command is keyboard-driven — the README carries the full
key map (arrows and Enter navigate; j/k and
g/G move and jump in lists, the vim style applies
except in filter where they are typed into the query; Esc aborts
with exit 1 except in pager, where it finishes like
q; Ctrl+C aborts with 130). There is no mouse.
Color follows one contract everywhere: --no-ansi is final,
--ansi outranks every environment rule, and
FORCE_COLOR, CLICOLOR_FORCE, NO_COLOR,
CLICOLOR, and TERM=dumb resolve in that order —
the README's Environment section carries the full ladder.
Auto-discovery
candy-scriptui uses PHP attributes to auto-discover commands at runtime. Mark any class extending Symfony\Component\Console\Command\Command with #[Command] (add class-level #[Flag] attributes to declare options — additive, never required) and Application::scan() registers it once the class is loaded:
namespace My\Commands;
use SugarCraft\ScriptUi\Attribute\{Command, Flag};
use Symfony\Component\Console\Command\Command as SymfonyCommand;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
#[Command(name: 'mycmd', description: 'Does something useful.', descriptionSection: 'Longer help text.')]
#[Flag(name: 'format', short: 'f', description: 'Output format.', default: 'json')]
final class MyCommand extends SymfonyCommand
{
protected function execute(InputInterface $input, OutputInterface $output): int
{
$output->writeln('format=' . $input->getOption('format'));
return self::SUCCESS;
}
}
use SugarCraft\ScriptUi\Application;
// scan() registers the #[Command] classes that are already loaded under the
// namespace, so load them first.
class_exists(\My\Commands\MyCommand::class);
$app = new Application();
$app->scan('My\Commands');
$app->run(); // mycmd --format yaml → format=yaml
New attribute types
| Type | Namespace | Role |
|---|---|---|
Command | SugarCraft\ScriptUi\Attribute\Command | #[Attribute] for auto-registering commands |
Flag | SugarCraft\ScriptUi\Attribute\Flag | #[Attribute] for declarative CLI options |
ValueEnum | SugarCraft\ScriptUi\Attribute\ValueEnum | Constrained enum for flag values |
CommandScanner | SugarCraft\ScriptUi\Discovery\CommandScanner | Namespace scanner for #[Command] classes |
Application::scan() | SugarCraft\ScriptUi\Application | Opt-in discovery method |
Enhanced help
| Type | Namespace | Role |
|---|---|---|
Alias | SugarCraft\ScriptUi\Attribute\Alias | #[Attribute] registering CLI command aliases |
Example | SugarCraft\ScriptUi\Attribute\Example | #[Attribute] adding example usage to help output |
HelpFormatter | SugarCraft\ScriptUi\Help\HelpFormatter | Renders enhanced help from #[Alias]/#[Example] attributes |
TypoSuggester | SugarCraft\ScriptUi\Help\TypoSuggester | Typo suggestions for unknown commands — prefix hits or Levenshtein distance ≤ 2, capped at five |
Output channels & environment
Data (chosen value, rendered table, completion script) goes to STDOUT raw and byte-exact; diagnostics go to STDERR; the interactive frame is painted to the controlling tty (or STDERR when that is the terminal), never into the capture stream. Because STDOUT is raw, quote every capture and never eval it when the input is third-party.
Recent additions: cursor mode has a default; pager gains --hard-wrap and --fade; confirm gains --pointer; format gains --code, --foreground, and --background, and its refusals are localized like every other command's; the color tier is derived from TERM; CANDY_SCRIPTUI_NO_DECORATION strips decoration; an intake read that times out exits 124; a read-only allow-listed GUM_<COMMAND>_<OPTION> mirror eases migration from gum (the README carries the disclosed table and the warning that names are not command-scoped); and the whole help surface (descriptions, option text, Aliases/Examples labels) is localized through the catalogs.
Shell completions + version
| Type | Namespace | Role |
|---|---|---|
BashCompletion | SugarCraft\ScriptUi\Completion\BashCompletion | Bash completion script generator |
ZshCompletion | SugarCraft\ScriptUi\Completion\ZshCompletion | Zsh completion script generator |
FishCompletion | SugarCraft\ScriptUi\Completion\FishCompletion | Fish completion script generator |
CompletionCommand | SugarCraft\ScriptUi\CompletionCommand | Built-in completion [--shell=bash|zsh|fish] subcommand |
Application::versionFromComposer() | SugarCraft\ScriptUi\Application | Version ladder: phar metadata first, then the nearest ancestor composer.json with a non-empty version, else a dev fallback |
candy-scriptui also reads CANDY_SCRIPTUI_* env fallbacks through a fail-closed allow-list of eighteen presentation option names — CANDY_SCRIPTUI_<OPTION> in uppercase arms that option when no explicit CLI flag is given, and names outside the list are ignored. Every option that answers for the user, grants capability, or redirects data is excluded by construction — allow-env, default, file, out, value, selected, type, shell, password — so a hostile environment can never retarget a sink or weaken a fail-closed flag. The roster is pinned in EnvVarFallbackTest. That exclusion is the lesson of the old universal option↔env mapping, where CANDY_SCRIPTUI_ALLOW_ENV='*' could arm format --type template to exfiltrate the whole environment and CANDY_SCRIPTUI_DEFAULT=yes silently answered confirm; both names now sit outside the allow-list and are ignored with no notice.
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Originally inspired by gum (Go); SugarCraft is developed as a native PHP project.
Demos.
VHS-recorded GIFs — thirteen demos, one per presentation subcommand. Regenerated automatically on every push that touches the source.
choose
Pick one or many items from a list.
confirm
Yes/no with exit-code semantics.
input
Read a single line.
write
Multi-line text editor.
file
Pick a file path.
filter
Filter stdin lines (substring by default).
format
Render Markdown via SugarMarkdown.
style
Apply foreground / bold to argv.
table
Render CSV with rounded borders.
pager
Scroll long input.
log
Leveled logging output.
spin
Spinner while running a command.