Авторы Aanand Prasad, Ben Firshman, Carl Tashian и Eva Parish (дизайн — Mark Hurrell) выпустили открытое руководство Command Line Interface Guidelines. Оно обновляет классические принципы UNIX под современный подход: CLI теперь — человеко-ориентированный текстовый интерфейс, а не просто REPL для скриптов.
Философия. Программы надо проектировать для людей, а не только для машин. Маленькие утилиты, которые хорошо комбинируются через pipes и JSON — всё ещё основа. Консистентность важна: пользователи запоминают паттерны, поэтому следуйте им, но не в ущерб удобству. Информации должно быть ровно столько, чтобы не путать и не заставлять гадать, зависла программа или нет. Делайте функциональность обнаруживаемой: подсказывайте, что делать дальше, давайте примеры, исправляйте опечатки. Взаимодействие с CLI — это разговор: пользователь пробует, ошибается, получает помощь. Программа должна чувствоваться надёжной, не вываливать stack trace и быть отзывчивой. И главное — эмпатия: вы на стороне пользователя, хотите, чтобы он преуспел.
Конкретные правила. Используйте библиотеку для парсинга аргументов (свою или стороннюю). Возвращайте 0 при успехе, ненулевой код при ошибке. В stdout — только основной вывод (в т.ч. машинный), в stderr — логи и ошибки (чтобы не попадали в pipe). Помощь показывайте по -h и --help. Если команда запущена без аргументов и не интерактивна — тоже выводите краткую справку с описанием, примерами и советом запустить --help. Не перегружайте -h — он всегда должен показывать помощь. Вешайте ссылки на веб-документацию в help. Начинайте help с примеров — они понятнее всего. Самые частые флаги выводите первыми. Форматируйте текст (например, bold-заголовки) без лишних escape-символов. Если юзер ошибся — предлагайте исправление (но не выполняйте его молча). Если команда ожидает pipe а stdin — терминал, выводите помощь сразу.
Вывод. Для человека — человекочитаемый вывод, для скриптов — машинный через --plain (одна запись на строку) и --json (структурированный JSON). При успехе выводите минимум, но если меняете состояние — обязательно сообщайте, что именно сделано. Сделайте простой способ увидеть текущее состояние (как git status) и подсказывайте, какую команду запустить дальше. И помните: правила можно нарушать, если это осознанно улучшает продукт.