CandyScriptui — SugarCraft

🐚 CandyScriptui

Composer-installable CLI of TUI primitives

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

13 subcommands — choose, confirm, file, filter, format, input, join, log, pager, spin, style, table, write. Drop into a shell script and instantly get a Charm-quality interactive UX.

Install

composer require sugarcraft/candy-scriptui

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.
candy-scriptui confirm "Really delete $file?" && rm "$file"

# Show a spinner while running a command.
candy-scriptui spin --title "Building..." -- make build

# Fuzzy-filter a list.
git branch | candy-scriptui filter

What's in the box

styleApply Sprinkles styling to argv (or stdin) and print.

choosePick one item from a list; prints the selection to stdout.

confirmYes/no — exit code 0 on yes, 1 on no.

filterFuzzy-filter over stdin lines.

input / writeSingle-line / multi-line text input.

fileFile picker — print the selected path.

formatRender Markdown via SugarMarkdown.

pagerScroll long input through a SugarWidgets Viewport.

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 styled strings horizontally / vertically.

Auto-discovery

CandyScriptui uses PHP attributes to auto-discover commands at runtime. Mark any class extending Symfony\Component\Console\Command\Command with #[Command] (plus a class-level #[Flag] per option) 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 (no trailing backslash), 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 (step 06.05)

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 (step 06.06)

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`	Levenshtein distance ≤ 2 typo suggestions for unknown commands

Shell completions + version (step 06.07)

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`	Reads version from root composer.json

CandyScriptui also respects CANDY_SCRIPTUI_* env var fallbacks — prefix any option name with CANDY_SCRIPTUI_ in uppercase to set it when no explicit CLI flag is provided.

Source & demos

Source on GitHub
Full README
Runnable examples
Originally inspired by gum (Go); SugarCraft is developed as a native PHP project.

Try the quickstart →

CLI Commands

Command	Description
completion	Emit shell completion script (bash · zsh · fish)
style	Apply Sprinkles styling to text
choose	Pick one item from a list
confirm	Yes/no confirmation
filter	Fuzzy-filter stdin lines
input	Read single-line text input
write	Read multi-line text input
file	File picker
format	Render Markdown
pager	Scroll long content
spin	Show spinner during command
table	Render CSV/TSV table
log	Leveled logging
join	Join styled strings