CLI UI

0.19.0 · active · verified Thu Apr 16

cli-ui is a Python library designed to help developers build aesthetically pleasing and user-friendly command-line interfaces. It provides tools for informative messages, error messages, progress indicators, formatting, and interactive user input (e.g., yes/no questions, choices). The current version is 0.19.0, and the project appears to be actively maintained, with recent updates and continued development on its GitHub repository.

Common errors

```
ModuleNotFoundError: No module named 'ui'
```
cause The Python package `cli-ui` is installed, but developers might attempt to import it directly using `import cli_ui` or similar, rather than the documented `import ui` alias.

fix Change your import statement from `import cli_ui` (or similar) to `import ui`.
```
My terminal output is full of strange characters instead of colors!
```
cause This typically occurs when `cli-ui` attempts to output colored text (using ANSI escape codes) to a destination that doesn't interpret them, such as a file, a non-ANSI-compliant terminal, or a pipe.

fix If running in a script or redirecting output, disable colorization with `ui.setup(color='never')` before any output. If in a terminal, ensure your terminal emulator supports ANSI colors.
```
Program hangs when calling ui.ask_yes_no() or ui.ask_choice() in a script.
```
cause Interactive input functions like `ask_yes_no` and `ask_choice` are designed for human interaction and will block execution indefinitely if run in a non-interactive environment (e.g., a CI/CD pipeline, a script without a controlling terminal).

fix Ensure interactive prompts are only used in interactive contexts. For automated scripts, provide default values or use command-line arguments instead of interactive input. You can also check if `sys.stdin.isatty()` before prompting.

Warnings

gotcha When redirecting output (e.g., to a file or pipe), `cli-ui`'s colorization might still emit ANSI escape codes. This can lead to unreadable output in non-terminal environments if not handled. The library's `color` configuration can be set to 'never' to prevent this.
Fix: Configure color output using `ui.setup(color='never')` or ensure output is directed to a TTY.
gotcha The `cli-ui` library offers `verbose` and `quiet` configuration options. Misunderstanding their precise behavior can lead to unexpected suppression or display of messages. `quiet` typically hides all but warnings, errors, and fatal messages, while `verbose` enables debug messages.
Fix: Consult the official documentation for `ui.setup()` to understand the exact behavior of `verbose` and `quiet` parameters and tailor them to your needs.
gotcha There are other projects with similar names, such as the JavaScript `cliui` (yargs/cliui) and `cli2gui`. Ensure you are referring to the correct Python `cli-ui` library to avoid confusion regarding features, installation, and breaking changes.

Install

pip install cli-ui Install latest version

Imports

ui
wrong:
```
import cli_ui
```
correct:
```
import ui
```
The library is installed as `cli-ui` but imported as `ui`.

Quickstart

This quickstart demonstrates common usage patterns for `cli-ui`, including printing colored messages, showing progress, and gathering user input through yes/no questions and choice selections.

import ui

# Informative messages
ui.info("This is", ui.green, "green", ui.reset, "text.")
ui.info_2("Starting", "Process X...")

# Progress indication
list_of_items = [f"Item {i}" for i in range(1, 6)]
for i, item in enumerate(list_of_items):
    ui.info_count(i, len(list_of_items), f"Processing {item}")

# User input
with_confirmation = ui.ask_yes_no("Proceed with action?", default=True)
if with_confirmation:
    fruits = ["apple", "orange", "banana"]
    selected_fruit = ui.ask_choice("Choose a fruit", choices=fruits)
    ui.info(f"You selected: {selected_fruit}")
else:
    ui.info("Action cancelled.")

view raw JSON →