Архив рассылок сообщества снова открыт. Читать письма 2003-2009
Главная/Блог/Разработка
Разработка15 мин чтенияНиколай Ковалёв

Как сделать удобную CLI-утилиту: UX командной строки

Справка, потоки вывода, коды выхода, цвет, JSON для скриптов, защита от опасных действий, каркас на Python и тесты интерфейса.

Ноутбук с открытым терминалом и цветным выводом консоли на столе под настольной лампой

Коротко: удобная CLI-утилита отвечает на --help и --version, пишет данные в stdout, а сообщения и ошибки в stderr, возвращает осмысленный код выхода, не красит вывод в пайпе, умеет отдавать JSON и не задаёт вопросов, когда её запускают из скрипта. Ниже разбираем эти правила по порядку, с примерами на Bash и Python и с чек-листом перед релизом.

Консольная утилита начинается как скрипт на двадцать строк, а через год ей пользуются коллеги, CI и cron. В этот момент становится видно, что у командной строки тоже есть интерфейс и его тоже кто-то проектирует, хотя кнопок здесь нет. Ошибки в нём такие же, как в вебе: непонятные сообщения, неочевидные умолчания, разрушительное действие без подтверждения.

Если у вашего продукта есть и консольный клиент, и веб-панель, сценарии для них лучше продумывать вместе: термины, порядок шагов и тексты ошибок должны совпадать. В YuSMP Group такие сценарии проектируют вместе с интерфейсом продукта, а эта статья про то, что разработчик может сделать сам в своей утилите.

Что делает CLI-утилиту удобной?

Удобная утилита предсказуема: человек угадывает, как её вызвать, а скрипт может на неё положиться. Хорошая проверка такая: сможет ли новый коллега выполнить типовую задачу, прочитав только вывод --help, и сможет ли скрипт отличить успех от ошибки, не разбирая текст.

У утилиты два пользователя одновременно:

  • Человек в терминале. Ему нужны подсказки, цвет, прогресс, понятные ошибки с советом, что делать дальше.
  • Программа: скрипт, пайп, CI, cron. Ей нужны стабильный формат вывода, код выхода и полное отсутствие интерактивных вопросов.

Почти все правила ниже сводятся к тому, чтобы утилита понимала, кто её запустил, и вела себя соответственно. Сборник рекомендаций Command Line Interface Guidelines формулирует ту же идею как «human-first design»: сначала удобство человека, но без поломки для машин.

Как назвать команды, аргументы и флаги?

Короткий ответ: следуйте соглашениям, которые пользователь уже знает по git, systemctl и docker, и не изобретайте свой синтаксис.

Структура «утилита → команда → аргументы»

Если утилита делает больше одного действия, разбейте её на подкоманды: tool user add, tool user list, tool backup run. Выберите один порядок, «существительное → глагол» или «глагол → существительное», и держитесь его во всех командах. Смешение tool add-user и tool user delete в одной утилите сразу ломает угадываемость.

Флаги лучше позиционных аргументов

Один позиционный аргумент, например файл или имя ресурса, читается нормально. Два и больше уже требуют помнить порядок: tool copy a b копирует из a в b или наоборот? Флаги снимают вопрос: tool copy --from a --to b. Исключение составляют списки однотипных значений вроде rm file1 file2 file3.

Соглашения по флагам

  • У каждого флага есть длинная форма --verbose; короткую -v давайте только самым частым.
  • Короткие флаги можно склеивать: -xvf равно -x -v -f. Так их разбирают getopt, argparse и большинство библиотек.
  • -- означает конец флагов: всё после него считается аргументами, даже если начинается с дефиса.
  • - вместо имени файла означает stdin или stdout.
  • Стандартные имена не переопределяйте: -h/--help, --version, -v/--verbose, -q/--quiet, -f/--force, -n/--dry-run, -o/--output.

Базовые правила синтаксиса описаны в разделе Utility Syntax Guidelines стандарта POSIX, а длинные опции с двумя дефисами пришли из GNU. Если пишете на Python, argparse или click соблюдают эти соглашения из коробки; в Bash для разбора есть getopts, приёмы описаны в статье Bash-скрипты для автоматизации.

Каким должен быть вывод --help?

Справка должна за один экран ответить на три вопроса: что делает утилита, как её вызвать и какой пример скопировать. Самые полезные строки справки — примеры, их читают первыми.

$ backupctl --help
backupctl — резервное копирование каталогов на удалённый сервер

Использование:
  backupctl run [--dry-run] <профиль>
  backupctl list [--json]
  backupctl restore --from <снимок> --to <каталог>

Примеры:
  backupctl run www              # снимок по профилю www
  backupctl run www --dry-run    # показать, что будет скопировано
  backupctl list --json | jq .   # снимки в машинном формате

Флаги:
  -n, --dry-run   ничего не менять, только показать план
  -q, --quiet     выводить только ошибки
      --json      вывод в JSON
  -h, --help      эта справка
      --version   версия утилиты

Документация: man backupctl

Что важно в этом примере:

  • Первая строка объясняет назначение одной фразой.
  • Справка открывается по -h, --help и help <команда>; у каждой подкоманды своя справка.
  • Справка уходит в stdout с кодом 0, её можно прогнать через less или grep.
  • При неверном вызове показывается не вся справка, а короткая строка использования и подсказка «см. backupctl --help».

Отдельно сделайте --version: одна строка с версией и, если есть, хешем коммита. Это первое, что попросят в баг-репорте.

Как разделить stdout и stderr?

Правило одно: в stdout идут данные, которые можно передать дальше по пайпу, а в stderr всё остальное: прогресс, предупреждения, ошибки, отладка.

Что выводимПотокПочему
Результат: список, JSON, путь к файлуstdoutЕго читает следующая команда в пайпе
Ошибки и предупрежденияstderrВидны человеку даже при перенаправлении вывода в файл
Прогресс-бар, спиннерstderr, только в TTYНе попадает в файл и в лог CI
Отладка (--verbose)stderrНе смешивается с данными
Справка по --helpstdoutПользователь сам её запросил, её удобно грепать

Типичная ошибка выглядит так: утилита печатает «Подключаюсь к серверу...» в stdout, и команда tool list | wc -l считает на одну строку больше. В Bash сообщение отправляется в stderr так:

log()  { printf '%s\n' "$*" >&2; }
die()  { printf 'ошибка: %s\n' "$*" >&2; exit "${2:-1}"; }

log "Подключаюсь к $HOST..."
list_snapshots          # результат в stdout

Ещё одно правило: успешная команда по умолчанию молчит или пишет минимум. Подробности выводятся по -v, тишина по -q.

Какие коды выхода возвращать?

Код 0 означает успех, любой другой означает ошибку. Скрипты, set -e, &&, CI и systemd опираются только на это число, а не на текст.

КодЗначениеОткуда
0УспехОбщепринято
1Общая ошибкаОбщепринято
2Неверное использование (так делают Bash и многие утилиты)Соглашение
64EX_USAGE: неверные аргументыsysexits.h
65EX_DATAERR: некорректные входные данныеsysexits.h
69EX_UNAVAILABLE: сервис недоступенsysexits.h
75EX_TEMPFAIL: временный сбой, можно повторитьsysexits.h
78EX_CONFIG: ошибка конфигурацииsysexits.h
126 / 127Нет прав на запуск / команда не найденаShell, не используйте сами
128+NЗавершение сигналом N (130 = Ctrl+C)Shell, не используйте сами

Не обязательно брать коды из sysexits.h, но набор нужно выбрать один раз и описать в документации. Особенно полезно отделять временные сбои (сеть, блокировка) от постоянных: тогда обёртка или systemd-юнит знают, когда стоит повторить запуск. Как systemd реагирует на коды выхода и перезапуски, разобрано в материале systemd на практике.

Как писать сообщения об ошибках?

Хорошее сообщение об ошибке отвечает на три вопроса: что случилось, почему и что сделать. Стек вызовов человеку по умолчанию не нужен, его показывают по --verbose или --debug.

Сравните два варианта:

# плохо
Traceback (most recent call last):
  ...
FileNotFoundError: [Errno 2] No such file or directory: '/etc/backupctl/www.toml'

# хорошо
ошибка: профиль «www» не найден (/etc/backupctl/www.toml)
  доступные профили: db, media
  создать новый: backupctl profile init www

Ещё несколько правил:

  • Ошибка в начале строки и с префиксом (ошибка: или имя утилиты), чтобы её было легко найти в логе.
  • Главное в последней строке вывода: её видно, даже если выше прокрутилось много текста.
  • Опечатка в команде лечится подсказкой «возможно, вы имели в виду restore?», как это делают git и cargo.
  • Одна причина — одно сообщение. Десять одинаковых строк для десяти файлов лучше свернуть в одну со счётчиком.

Когда нужен цвет, прогресс и интерактив?

Только когда вывод идёт в терминал и с утилитой работает человек. Проверка на TTY занимает одну строку, и без неё цветные escape-последовательности оказываются в логах и ломают парсинг.

# Bash
if [ -t 1 ] && [ -z "${NO_COLOR:-}" ] && [ "${TERM:-}" != "dumb" ]; then
  RED=$'\e[31m'; RESET=$'\e[0m'
else
  RED=''; RESET=''
fi
# Python
import os, sys
use_color = (sys.stdout.isatty()
             and "NO_COLOR" not in os.environ
             and os.environ.get("TERM") != "dumb")

Правила для цвета

  • Уважайте переменную NO_COLOR: если она задана, цвета нет. Это общее соглашение многих консольных программ.
  • Дайте флаг --color=auto|always|never, как у ls и grep.
  • Цвет только дублирует смысл: «ошибка» в начале строки остаётся и без красного.

Правила для интерактива

  • Вопросы задаются только если stdin это терминал ([ -t 0 ]). В скрипте утилита не должна зависать в ожидании ответа.
  • У каждого вопроса есть флаг-замена: --yes, --password-file, --non-interactive.
  • Пароль не принимается флагом: он попадёт в историю shell и в ps. Читайте его из файла, переменной окружения или запросом без эха.

Правила для прогресса

Если операция длится дольше пары секунд, покажите, что утилита жива: спиннер или прогресс-бар в stderr. В не-TTY режиме замените его на редкие строки вида «скопировано 120/500», иначе лог CI заполнится тысячами перерисовок.

Как сделать вывод удобным для скриптов?

Дайте машинный формат флагом, а человеческий оставьте по умолчанию. Обычно это --json или --output json|table|plain.

$ backupctl list
СНИМОК             ПРОФИЛЬ  РАЗМЕР   ДАТА
www-20261116-0300  www      1.2 GiB  2026-11-16 03:00
db-20261116-0310   db       340 MiB  2026-11-16 03:10

$ backupctl list --json | jq -r '.[] | select(.profile=="db") | .id'
db-20261116-0310

Что ещё помогает скриптам:

  • Стабильный формат. Поля JSON не переименовываются между минорными версиями; новые поля добавляются, старые не исчезают без предупреждения.
  • Табличный вывод без украшений по флагу --plain: одна запись на строку, разделитель табуляция, без рамок и выравнивания.
  • Размеры и даты в машинном виде в JSON: байты числом, время в ISO 8601 или Unix time.
  • Идемпотентность. Повторный tool user add bob не падает, если пользователь уже есть, или падает с отдельным кодом, который скрипт может обработать.

Где хранить конфиг и в каком порядке его читать?

Конфиги кладите по спецификации XDG Base Directory, а приоритет источников держите стандартным: чем ближе источник к конкретному запуску, тем он сильнее.

  1. Флаги командной строки.
  2. Переменные окружения (BACKUPCTL_HOST).
  3. Конфиг проекта в текущем каталоге (./.backupctl.toml).
  4. Пользовательский конфиг ($XDG_CONFIG_HOME/backupctl/config.toml, по умолчанию ~/.config/backupctl/).
  5. Системный конфиг (/etc/backupctl/).
  6. Значения по умолчанию в коде.

Кэш кладите в $XDG_CACHE_HOME (~/.cache), данные в $XDG_DATA_HOME (~/.local/share), а не в новую точку-папку в домашнем каталоге. Полезна команда tool config show, которая печатает итоговые значения и откуда каждое взято: она экономит часы отладки, когда переменная окружения тихо перекрывает файл.

Как защититься от опасных действий?

Деструктивная операция должна быть явной, обратимой где возможно и проверяемой заранее.

  • --dry-run показывает план без изменений. Это лучший способ проверить команду на проде.
  • Подтверждение в TTY для удаления и перезаписи; в скрипте вместо вопроса нужен явный --force или --yes.
  • Подтверждение вводом имени для самых опасных действий: «введите имя базы, чтобы удалить её».
  • Корректная реакция на Ctrl+C: перехватите SIGINT, уберите временные файлы и выйдите с кодом 130. Повторный Ctrl+C завершает утилиту сразу.
  • Атомарная запись: пишите во временный файл и переименовывайте его mv, тогда прерванная операция не оставит половину конфига.
tmp=$(mktemp)
trap 'rm -f "$tmp"; exit 130' INT
trap 'rm -f "$tmp"' EXIT
generate_config > "$tmp" && mv "$tmp" /etc/app/config.toml

Что ещё влияет на удобство утилиты?

Скорость запуска

Утилиту вызывают десятки раз в день, иногда в цикле. Если --help открывается секунду, ей будут пользоваться реже. Тяжёлые импорты загружайте лениво, внутри конкретной команды, а не при старте.

Автодополнение команд в bash, zsh и fish

Генерация completion-скриптов для bash, zsh и fish есть в click, typer, cobra и clap. Добавьте команду tool completion bash и строку в README, как её подключить. Пакет в дистрибутиве кладёт скрипт в /usr/share/bash-completion/completions/.

man-страница и установка

Справки по --help достаточно для старта, но man-страницу ищут по привычке. Её несложно сгенерировать из той же разметки, что и справку. Установка должна быть одной командой: пакет, pipx install, статический бинарник. Список базовых команд, которые стоит знать до начала, есть в статье 25 команд терминала.

Совместимость флагов между версиями

Интерфейс утилиты — это контракт. Удаление флага или смена формата вывода ломают чужие скрипты, поэтому сначала выводите предупреждение «флаг --old устарел, используйте --new», а удаляйте его в следующей мажорной версии.

Пример: каркас утилиты на Python

Ниже минимальный каркас на стандартном argparse, который уже соблюдает большую часть правил: подкоманды, примеры в справке, stderr для сообщений, коды выхода, --json, --dry-run, NO_COLOR и Ctrl+C. Сторонних зависимостей нет, работает на Python 3.8 и новее.

#!/usr/bin/env python3
"""backupctl — резервное копирование каталогов."""
import argparse, json, os, sys

__version__ = "1.4.0"
EX_OK, EX_ERR, EX_USAGE, EX_CONFIG = 0, 1, 64, 78

def err(msg: str) -> None:
    red = sys.stderr.isatty() and "NO_COLOR" not in os.environ
    prefix = "\033[31mошибка:\033[0m" if red else "ошибка:"
    print(f"{prefix} {msg}", file=sys.stderr)

def cmd_list(args) -> int:
    snaps = [{"id": "db-20261116-0310", "profile": "db", "bytes": 356515840}]
    if args.json:
        json.dump(snaps, sys.stdout, ensure_ascii=False)
        print()
    else:
        for s in snaps:
            print(f"{s['id']}\t{s['profile']}\t{s['bytes']}")
    return EX_OK

def cmd_run(args) -> int:
    cfg = f"/etc/backupctl/{args.profile}.toml"
    if not os.path.exists(cfg):
        err(f"профиль «{args.profile}» не найден ({cfg})")
        print(f"  создать: backupctl profile init {args.profile}", file=sys.stderr)
        return EX_CONFIG
    if args.dry_run:
        print(f"план: снимок профиля {args.profile}, изменений не будет")
        return EX_OK
    # ... само копирование ...
    return EX_OK

def build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(
        prog="backupctl",
        description="Резервное копирование каталогов на удалённый сервер.",
        epilog="примеры:\n  backupctl run www --dry-run\n  backupctl list --json | jq .",
        formatter_class=argparse.RawDescriptionHelpFormatter)
    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
    sub = p.add_subparsers(dest="cmd", required=True)
    r = sub.add_parser("run", help="сделать снимок по профилю")
    r.add_argument("profile")
    r.add_argument("-n", "--dry-run", action="store_true", help="только показать план")
    r.set_defaults(func=cmd_run)
    l = sub.add_parser("list", help="список снимков")
    l.add_argument("--json", action="store_true", help="вывод в JSON")
    l.set_defaults(func=cmd_list)
    return p

def main() -> int:
    args = build_parser().parse_args()
    try:
        return args.func(args)
    except KeyboardInterrupt:
        return 130

if __name__ == "__main__":
    sys.exit(main())

Обратите внимание на детали. argparse сам отвечает на -h и при неверном вызове печатает строку использования в stderr с кодом 2. Сообщения об ошибках уходят в stderr, а результат и план --dry-run в stdout. Цвет включается только в терминале. Табличный вывод разделён табуляцией и без рамок, поэтому его читают cut и awk.

Как тестировать интерфейс CLI?

Интерфейс утилиты тестируется так же, как API: вызовом с заданными аргументами и проверкой stdout, stderr и кода выхода. Достаточно нескольких сценариев на каждую команду.

  • Успешный вызов: код 0, ожидаемые данные в stdout, пустой или короткий stderr.
  • Неверные аргументы: ненулевой код, подсказка в stderr, пустой stdout.
  • Пайп: в выводе нет escape-последовательностей (\033[), нет прогресс-бара.
  • JSON: вывод --json разбирается jq или json.loads без ошибок.
  • Без TTY: при stdin из /dev/null утилита не зависает на вопросе.
out=$(backupctl list --json 2>/dev/null) && echo "$out" | jq -e 'type=="array"' >/dev/null
backupctl run nosuch </dev/null; test $? -eq 78
backupctl list | grep -q $'\e\[' && echo "цвет в пайпе!" && exit 1

Для Python удобны pytest и subprocess.run(..., capture_output=True), для Bash-утилит есть фреймворк bats. Такие тесты стоит гонять в CI на каждом коммите: они ловят именно те регрессии, которые ломают чужие скрипты.

Чек-лист перед релизом CLI-утилиты

  1. -h, --help и --version работают и возвращают 0.
  2. В справке есть назначение одной строкой и не меньше двух примеров.
  3. Данные идут в stdout, всё остальное в stderr.
  4. Коды выхода описаны; 0 только при полном успехе.
  5. Сообщения об ошибках говорят, что сделать дальше; стек вызовов только по --debug.
  6. Цвет и прогресс отключаются в пайпе и при NO_COLOR.
  7. Нет интерактивных вопросов без TTY; у каждого вопроса есть флаг-замена.
  8. Есть --json или --plain для скриптов.
  9. Опасные команды поддерживают --dry-run и требуют подтверждения.
  10. Конфиг читается из XDG-путей с понятным приоритетом.
  11. Ctrl+C не оставляет мусора и возвращает 130.
  12. Есть автодополнение и способ установки одной командой.

Частые вопросы об интерфейсе командной строки

На чём писать CLI-утилиту: Bash, Python или Go?

Bash подходит для обёрток над другими командами до пары сотен строк. Python с argparse, click или typer удобен, когда нужна логика, конфиги и JSON. Go и Rust выбирают, когда важны быстрый старт и один статический бинарник без зависимостей на сервере.

Чем аргумент отличается от флага?

Аргумент позиционный: его смысл определяется местом в команде, как у cp источник назначение. Флаг именованный и начинается с дефиса: --output file.txt. Флаги проще читать и расширять, поэтому для всего, кроме одного главного аргумента, лучше использовать их.

Нужно ли переводить сообщения утилиты на русский?

Если утилитой пользуются только внутри команды, пишите на том языке, на котором вам удобнее. Для открытого проекта английский по умолчанию плюс локализация через gettext и LANG. Коды выхода и поля JSON не переводятся: на них опираются скрипты.

Как проверить, что утилита правильно ведёт себя в пайпе?

Запустите её как tool list | cat: цвет и прогресс должны исчезнуть. Команда tool list 2>/dev/null должна показать только данные, а tool bad-command; echo $? — ненулевой код. Эти проверки легко добавить в автотесты.

Что делать, если команд стало слишком много?

Сгруппируйте их по объектам (tool user ..., tool backup ...) и покажите в справке группы, а не плоский список из тридцати пунктов. Редкие команды можно убрать в tool help --all.

Как правильно спрашивать пароль в консоли?

Читайте его без эха (read -s в Bash, getpass в Python) и только в TTY. Для скриптов дайте --password-file или переменную окружения. Флаг --password=... не делайте: значение видно в ps и сохраняется в истории shell.