All 22 apps

CandyScriptui

Composer-installable CLI of TUI primitives

inspired by charmbracelet/gum cli shell-script one-shot

CandyScriptui code coverage

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

styleApply ANSI styling to argv (or stdin) and print.
choosePick one or many items from a list; prints the selection to stdout.
confirmYes/no — exit code 0 on yes, 1 on no.
filterFilter stdin lines — substring match by default, fuzzy with --fuzzy.
input / writeSingle-line / multi-line text input.
fileFile picker — print the selected path.
formatRender Markdown / code / template / emoji via SugarMarkdown.
pagerScroll long content; start at a heading with --match.
spinShow a spinner while running an external command.
tableRender a CSV / TSV table with rounded borders.
logLeveled logging output (debug / info / warn / error / fatal).
joinConcatenate lines or arguments horizontally / vertically; prints raw text.
completionEmit a shell completion script (bash · zsh · fish).
versionPrint the version — phar metadata first, then the composer.json ladder, then a dev fallback.

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

TypeNamespaceRole
CommandSugarCraft\ScriptUi\Attribute\Command#[Attribute] for auto-registering commands
FlagSugarCraft\ScriptUi\Attribute\Flag#[Attribute] for declarative CLI options
ValueEnumSugarCraft\ScriptUi\Attribute\ValueEnumConstrained enum for flag values
CommandScannerSugarCraft\ScriptUi\Discovery\CommandScannerNamespace scanner for #[Command] classes
Application::scan()SugarCraft\ScriptUi\ApplicationOpt-in discovery method

Enhanced help

TypeNamespaceRole
AliasSugarCraft\ScriptUi\Attribute\Alias#[Attribute] registering CLI command aliases
ExampleSugarCraft\ScriptUi\Attribute\Example#[Attribute] adding example usage to help output
HelpFormatterSugarCraft\ScriptUi\Help\HelpFormatterRenders enhanced help from #[Alias]/#[Example] attributes
TypoSuggesterSugarCraft\ScriptUi\Help\TypoSuggesterTypo 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

TypeNamespaceRole
BashCompletionSugarCraft\ScriptUi\Completion\BashCompletionBash completion script generator
ZshCompletionSugarCraft\ScriptUi\Completion\ZshCompletionZsh completion script generator
FishCompletionSugarCraft\ScriptUi\Completion\FishCompletionFish completion script generator
CompletionCommandSugarCraft\ScriptUi\CompletionCommandBuilt-in completion [--shell=bash|zsh|fish] subcommand
Application::versionFromComposer()SugarCraft\ScriptUi\ApplicationVersion 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

Try the quickstart →

Demos.

VHS-recorded GIFs — thirteen demos, one per presentation subcommand. Regenerated automatically on every push that touches the source.

choose

choose

Pick one or many items from a list.
confirm

confirm

Yes/no with exit-code semantics.
input

input

Read a single line.
write

write

Multi-line text editor.
file

file

Pick a file path.
filter

filter

Filter stdin lines (substring by default).
format

format

Render Markdown via SugarMarkdown.
style

style

Apply foreground / bold to argv.
table

table

Render CSV with rounded borders.
pager

pager

Scroll long input.
log

log

Leveled logging output.
spin

spin

Spinner while running a command.
join

join

Concatenate chunks; raw text out.