Why output design matters

A command-line tool's output is its user interface. Every time your tool runs, a human — or a script acting on their behalf — reads what it prints and decides what to do next. That decision is faster, easier, and less error-prone when the output is designed rather than dumped.

The wall-of-text problem

Most beginner tools print everything they know: every file processed, every value computed, every step taken. This feels safe — nothing is hidden — but in practice it creates a new problem: finding the one line that matters requires scanning the whole wall.

Think about how you read a well-written report. The executive summary is at the top. Details come below, in sections you can skip if they do not concern you. The most important fact is on the first line, not buried on line 47.

CLI output should follow the same principle. Lead with the result. Follow with supporting detail. Hide verbose internals behind a --verbose flag.

Colour signals state

Humans parse colour faster than text. A green "Success" is understood before the word is fully read. A red "Error" triggers attention. A yellow "Warning" sits in between.

This is not decoration. It is information density. A status line like:

[OK]   built 42 files in 1.2s
[WARN] 3 files skipped (unsupported format)
[ERR]  output directory not writable

communicates the same thing as a paragraph of prose, but in three seconds of scanning rather than twenty.

Structure enables scanning

Tables, indented hierarchies, and aligned columns let users skip to what they care about. A flat list of 200 filenames with results mixed in is hard to scan. A table with a Status column is easy: run your eye down one column, stop at anything that is not OK.

The same logic applies to errors. An error message with a clear label, the file name, the line number, and the reason is actionable. A stack trace with no summary is not.

Output is a first-class concern

The logic inside your tool and the output it produces deserve equal attention. A tool that works correctly but prints confusing output will frustrate users, generate support requests, and get replaced.

The Rich library for Python makes this easy: it provides print markup, tables, progress bars, and panels with very little code. The next few lessons walk through its core features.

Where to go next

Next: Rich text output — using rich.print(), Panel, and Syntax to add colour, hierarchy, and code highlighting to your tool's output.