CLI в скриптах¶
Получить JSON¶
В терминале ycli печатает таблицы, а при передаче по конвейеру — JSON. Формат можно задать явно глобальным флагом --format / -o (auto, json, yaml, pretty, csv, markdown, ndjson, name) до команды или после неё:
ycli tracker issues get TRACKER-1 | jq . # JSON, потому что вывод передаётся по конвейеру
ycli -o yaml wiki pages get onboarding
ycli wiki pages get onboarding -o json
Ключи — это имена полей самого API (createdAt в Трекере, created_at в Вики), поэтому фильтры из документации Яндекса работают как есть.
Фильтрация вывода¶
Своего фильтра у ycli нет: передайте JSON по конвейеру в jq.
ycli tracker issues get TRACKER-1 -o json | jq -r .summary
ycli tracker issues search 'Queue: TEST' -o json | jq -r '.items[].key'
-o json задаёт формат явно; без него по конвейеру всё равно уходит JSON.
Таблица или один элемент на строку¶
-o csv и -o markdown печатают таблицу, -o ndjson — по одному элементу на строку:
ycli tracker issues search 'Queue: TEST' -o csv > issues.csv
ycli tracker queues list -o markdown >> report.md
ycli tracker issues search 'Queue: TEST' -o ndjson | jq -r .key
- Столбцы — это поля, которые ycli знает у объекта такого вида; они одни и те же при любом ответе. У поля, которое сервис добавил позже, столбца нет; его печатает
-o json. - Вложенный объект раскладывается в столбцы с именем через точку (
status.key); список остаётся одной ячейкой, текстом JSON. - Команда, которая отвечает одним объектом, печатает таблицу из одной строки или одну строку.
csv— это UTF-8 без метки порядка байтов, строки кончаются одним переводом строки, а ячейка — текст сервиса как есть. Ячейку, которая начинается с=, таблица прочтёт как формулу: открывайте файл с чужим текстом, помня об этом.- Где список остановился, сказано в stderr, как и при
-o pretty: в stdout только строки.
Передать вывод одной команды другой¶
-o name печатает идентификатор каждого объекта на отдельной строке: то, что принимает команда, которая его читает.
ycli tracker issues search 'Queue: TEST' -o name | xargs -n1 ycli tracker issues get
new=$(ycli tracker issues create --queue TEST --summary 'From a script' -o name)
- Объект, который лежит внутри другого, печатает свой идентификатор:
ycli tracker comments list TEST-1 -o nameпечатает id комментариев, а ключ задачи добавляете вы. - Команде, у результата которой нет идентификатора (выдача доступа, счётчик), отказывают до отправки запроса, код возврата 2.
- Команда DataLens, которая запускает долгую операцию (облачное окружение, кластер Spark или Trino), отвечает операцией, поэтому
-o nameпечатает id операции — тот, что принимаетycli datalens lakehouseoperations get, а не id создаваемого объекта. - Ответ, в котором у объекта нет идентификатора, — это ошибка: ничего не печатается, поэтому скрипт не обработает меньше объектов, чем было в списке.
- С
--dry-runвместо объекта приходит план, и он печатается как JSON.
Длинный список по частям¶
Список останавливается на 500 элементах, если не сказать иначе. --limit N берёт первые N, --all — всё, а --next продолжает с места, где остановился прошлый запуск. -o json и -o yaml печатают то же, что отдают инструмент MCP и SDK: {items, truncated, next, total}, так что скрипт берёт токен через jq -r .next. Таблица (-o pretty) печатает строки, а где список остановился — в stderr, готовой строкой. Строка говорит, что запуск остановился на лимите, а не что что-то осталось: это покажет только следующий запуск, и он может не дать ничего.
$ ycli tracker issues search 'Queue: DE' --limit 100 > first.json
stopped at 100 of 752; go on with: ycli tracker issues search 'Queue: DE' --next eyJ2IjoxLCJvZiI6… (or --all)
$ ycli tracker issues search 'Queue: DE' --limit 100 --next eyJ2IjoxLCJvZiI6… > second.json
Токен несёт свой список: с --next задают только лимит и то, без чего команду не вызвать, причём таким же, как было: аргумент, который расходится с токеном, получает отказ с его именем, а не отбрасывается молча. Токен поиска задач Трекера с прокруткой (--scroll-type) работает один раз; любой другой токен можно использовать повторно. В нём лежит и собственный токен прокрутки, поэтому ycli tracker issues scroll-clear --next TOKEN освобождает прокрутку до истечения её срока; этот токен бесполезен без ваших учётных данных и перестаёт действовать вместе с прокруткой. Токен продолжает список только в той организации, где он получен: под другой учётной записью будет отказ, а не запуск. Список, который уже нельзя продолжить, завершается кодом 9: начните его заново без токена. Запуск, которому нужно больше страниц, чем YCLI__HTTP__MAX_PAGES, останавливается на этом пределе и говорит об этом так же, с токеном для продолжения. Маленький первый --limit задаёт размер страниц для всех следующих частей, поэтому берите первую часть такой же величины, какими собираетесь продолжать.
Удаление и выдача доступа без запроса подтверждения¶
Команда, которая уничтожает данные или выдаёт доступ (роль на форме или странице, права очереди, привязка доступа или встраивание в DataLens), в терминале просит подтверждения. В скрипте спросить некого, поэтому она завершается с кодом 2, пока вы не передадите --yes / -y:
ycli tracker boards delete 7 --yes
ycli wiki access create 7 --role reader --user-uid 9001 --yes
О том, что команда выдаёт доступ, сказано в её справке. --dry-run ни о чём не спрашивает: он ничего не отправляет.
Предпросмотр записи¶
--dry-run ничего не записывает, а печатает запрос (метод, URL, тело — но никогда не токен) в том же формате -o, и завершается с кодом 0. Секрет в теле, например пароль подключения DataLens, печатается как ***, поэтому вывод безопасен в логе CI. Такое значение давайте из файла вне репозитория с правами 600: через --body-file или одним полем через -F password=@secret.txt. Набранное в командной строке, оно остаётся в истории оболочки. Файл одного поля пишите без перевода строки в конце (printf %s 'секрет' > secret.txt), иначе перевод строки уйдёт вместе с секретом. Чтения всё равно выполняются, поэтому команда, которая сначала читает, а потом пишет, покажет только свою первую запись.
ycli tracker boards delete 7 --dry-run
Ветвление по коду возврата¶
У каждого вида ошибки свой код возврата; они перечислены в справочнике по конфигурации.
ycli tracker issues get TRACKER-1 > issue.json
case $? in
0) echo found ;;
3) echo "no such issue" ;;
6) echo "try again later" ;;
esac
Автодополнение команд по Tab¶
В ycli несколько сотен команд; пусть их дополняет оболочка. Сначала установите ycli как инструмент (uv tool install yandex-cli), чтобы команда оставалась в PATH, затем выполните:
ycli --install-completion # для текущей оболочки: bash, zsh, fish или PowerShell
Перезапустите терминал. Автодополнение устанавливается для того имени, которым вы запускали команду: если вы пользуетесь длинным именем, выполните yandex-cli --install-completion ещё раз. ycli --show-completion печатает скрипт, а не устанавливает его.
О запуске ycli в конвейере см. Использование в CI.