Перейти к основному содержимому

CLI

Command Line Interface (интерфейс командной строки) — это способ взаимодействия с программой путём ввода строк текста, называемых командами.

Команды выполняются интепретатором командной строки (часто используется термин оболочка, shell); например, bash и zsh для Linux или PowerShell для Windows.

Знание CLI полезно для написания скриптов: программы, имеющие CLI, обычно легко автоматизируются, чего нельзя сказать про графический интерфейс.

Структура​

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

┌─1─┐ ┌2─┐            # 1. command
chmod a=rw data.json  # 2. argument
│     └─────3──────┘  # 3. arguments
└────────4─────────┘  # 4. command line

Соглашения​

Единого и обязательного формата для аргументов командной строки не существует. Программа получает аргументы в виде обычного массива строк и разработчики могут обрабатывать эти строки как посчитают нужным.

Тем не менее существуют соглашения, которые задают некоторые рамки поведения программы и часто соблюдаются, особенно если CLI программы поддерживает широкий спектр возможностей.

Подкоманды:​

Часто программа может выполнять разные функции и тогда первые аргументы понимаются как подкоманда. Если подкоманд много, их можно разбить по группам.

git log                # subcommand
gitea admin user list  # command groups

Виды аргументов:​

Обычно для выполнения программы ей нужно передать какое-то количество аргументов (вместо термина "аргумент" можно встретить термин "параметр"). Под словом "опция" (option) обычно понимается необязательный аргумент.

Под словом "флаг" (flag) обычно понимается опция, которая не имеет собственного значения, она просто есть или нет. В качестве значения используется логический тип: если флаг указан, значение true, иначе false.

Для опций отсутствует понятие порядка, поэтому необходимо указывать их имена. Часто для опции вводится однобуквенное сокращение. Для сокращений используется префикс -, а для длинных названий --.

-h, --help
-v, --version

Флаги можно объединять: запись вида -abc эквивалентна -a -b -c.

Значения аргументов:​

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

Значением опции выступает следующий токен. Также используется синтаксис вида key=value: значение отделяется знаком равно.

command -o value
command --option value
command --option=value

Документирование​

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

Синопсис​

Квадратные скобки вокруг аргумента указывают на то, что он необязательный. Если их несколько, каждый заключается в отдельные скобки.

vitest [--run] [--testNamePattern=NAME]

Фигурные скобки используются для указания на выбор одного из взаимоисключающих вариантов. Каждый вариант отделяется вертикальной чертой.

git merge {--continue | --abort | --quit}

Три точки используются, когда можно указать несколько значений аргумента.

eslint . [--ext=EXT,...]

Форматирование​

Если строка превышает 80 символов, перенести на новую строку (добавив \); после первой строки делать отступ на четыре пробела.

Пример​

gcloud COMMAND [--account=ACCOUNT] [--configuration=CONFIGURATION] \
    [--flatten[=KEY,...]] [--format=FORMAT] [--project=PROJECT_ID] \
    [--verbosity=VERBOSITY; default="warning"] [--version, -v] \
    [-h] [--trace-token=TRACE_TOKEN] [--no-user-output-enabled]

Источники: