pterm-go-cli

name	pterm-go-cli
description	Build and improve Go CLI output, terminal UI, and interactive prompts using PTerm. Use when the user asks to beautify terminal output, add tables, charts, spinners, progress bars, or live areas, add interactive prompts such as confirm, select, multiselect, or text input, improve Go CLI UX, or explain how to use PTerm APIs and options.
metadata	{"tags":"golang, go, cli, terminal, terminal ui, tui, pterm, prompts, interactive input"}

PTerm Go CLI Skill

What This Skill Does

Use this skill to design, implement, or refactor Go CLI interfaces with github.com/pterm/pterm, based on the official project documentation and _examples.

This skill covers:

• Pretty output (status messages, sections, headers, boxes, trees, tables)
• Data visualization (bar charts, heatmaps)
• Live terminal feedback (spinners, progress bars, live areas)
• Interactive input (confirm, continue, select, multiselect, text input)
• Styling (ANSI colors, RGB/TrueColor, custom styles)
• Logging integration (DefaultLogger, slog handler)

Quick Start

Install PTerm inside a Go modules project:

go get github.com/pterm/pterm

Start with defaults, then add options via fluent chaining:

package main

import "github.com/pterm/pterm"

func main() {
    pterm.Info.Println("Starting task")
    pterm.DefaultTable.WithHasHeader().WithData([][]string{
        {"Item", "Status"},
        {"Download", "Done"},
    }).Render()
}

Core Workflow

For any PTerm request, follow this sequence:

1. Pick the UX mode:
   • static output (Println, Render)
   • live output (Start -> updates -> Stop)
   • interactive prompt (Show)
2. Start from pterm.DefaultX printer.
3. Add only required options via With... methods.
4. Choose output form:
   • direct terminal output: Render, Println
   • compose first as string: Srender, Sprint, then print/update
5. Ensure lifecycle cleanup for live printers (Stop(), or final state methods such as spinner Success()/Fail()).

Runtime Mode Gate

Before choosing components, classify runtime mode:

• Rich mode (interactive TTY): use full PTerm output, live printers, interactive prompts.
• Plain mode (CI/non-interactive): avoid Show() prompts and avoid repaint-heavy live printers.
• Machine mode (output consumed by tools): avoid ANSI styles, RGB colors, and box-drawing-heavy layouts.

Decision rules:

• Unknown total work: prefer Spinner.
• Known total work: prefer Progressbar.
• Multiple concurrently updating streams: prefer DefaultMultiPrinter only in rich mode.
• If output must be parseable/replayable: use stable line-based messages and tables without decorative effects.

Reference Loading Rules

• Read references/quick-recipes.md for copy-ready patterns by task.
• Read references/api-patterns.md when you need API behavior, method semantics, or option decisions.
• Read references/components-index.md when mapping a user request to the right component/printer.
• Do not load all reference files by default; load only what is needed for the current task.

Choose the Right PTerm Component

• Status text/log-like messages: Info, Success, Warning, Error, DefaultSection, DefaultHeader
• Structured output: DefaultTable, DefaultTree, DefaultBulletList, DefaultBox, DefaultPanel
• Progress and live tasks: DefaultSpinner, DefaultProgressbar, DefaultArea, DefaultMultiPrinter
• User choices/input: DefaultInteractiveConfirm, DefaultInteractiveSelect, DefaultInteractiveMultiselect, DefaultInteractiveTextInput
• Metrics visualization: DefaultBarChart, DefaultHeatmap

Output Expectations

When implementing with PTerm:

• Keep output purposeful and readable; avoid decorative noise.
• Prefer consistent styles and prefixes for repeated messages.
• Match component choice to task type (do not use interactive prompts for non-interactive scripts).
• Use defaults first, then minimal customization.

When explaining to users:

• Include short, runnable Go snippets.
• Name the exact PTerm types/methods used.
• Mention terminal capability caveats when relevant (for example, TrueColor/RGB support).

Error Handling and Safety

PTerm operations are generally non-destructive, but apply these guardrails:

• Always handle returned errors from Start, Render, Srender, and Show in production code.
• For live printers, always end the lifecycle (Stop, Success, Fail, etc.) to avoid broken terminal state.
• For interactive text input, use masking for secrets (WithMask("*")) and do not print sensitive values.
• In CI/non-interactive environments, avoid blocking interactive prompts unless explicitly intended.

NEVER Patterns (PTerm in Production)

• NEVER call interactive Show() prompts when stdin is not a TTY; this can block CI/cron flows.
• NEVER assume RGB/TrueColor availability in automation; many terminals downgrade color support.
• NEVER leave live printers unclosed; unbalanced Start/Stop can corrupt subsequent terminal output.
• NEVER mix repaint-heavy live output with machine-parsed logs.
• NEVER echo captured secrets, even if input used WithMask("*").

Source of Truth

Base all guidance on:

• Official repository: https://github.com/pterm/pterm
• Official examples: https://github.com/pterm/pterm/tree/master/_examples