Skip to main content

Artisanal docs

Artisanal helps you build command-line tools and interactive terminal apps in Dart. You can use a small piece of it for nicer console output or build an entire application with keyboard, mouse, animation, and rich layouts.

You do not need to learn the whole toolkit before you begin. Pick the path that looks most like what you are building.

What do you want to build?​

A command or CLI​

Start with console output for messages, prompts, tables, and progress. Add the command runner if your app has subcommands, options, help text, or shell completion. Use styles when you want more control over colors and layout.

An interactive terminal app​

Artisanal offers two ways to structure one:

  • Choose the TEA runtime when you want a small, explicit Model → update → view loop and direct control over messages and commands.
  • Choose the widget system when your app has screens, forms, reusable components, navigation, or Flutter-style state.

Both use the same runtime and renderer, so this is a choice about how you want to organize your code—not a choice between separate platforms. If your app needs to share the screen with normal shell output, read the inline TUI guide.

A low-level renderer or terminal integration​

Use Ultraviolet when you need to draw cells directly, build a custom renderer, decode terminal input, or work with Kitty, Sixel, and iTerm2 images. Most applications can stay at the TUI or widget layer.

Common tasks​

I want to…Start here
Ask questions or show progress in a CLIConsole output
Add subcommands and flagsCommands and arguments
Style text, borders, and layoutsTerminal styling
Add inputs, lists, and reusable TEA componentsInteractive components
Render MarkdownMarkdown in the terminal
Draw charts or sequence diagramsTerminal charts
Test a widget appWidget testing
Record or replay a TUI sessionReplay and tracing
Show terminal imagesTerminal graphics
Understand how the packages fit togetherArchitecture

Packages at a glance​

  • artisanal contains CLI output, styling, the TEA runtime, and the umbrella APIs.
  • artisanal_widgets contains the widget framework and focused widget libraries.
  • ultraviolet contains low-level buffers, rendering, input, and terminal graphics.

Advanced and experimental topics​