Документация по терминалу сводится обычно к скриншотам с серым окном и видео на YouTube, где ничего нельзя скопировать. Asciinema предлагает другое: сессия записывается как текст с таймингами, а проигрыватель встраивается в веб-страницу, откуда зритель выделяет и копирует команды как обычный текст. Файлы на порядок легче видео, выглядят отлично и никогда не мылятся. В статье разбираем практику: запись и обработка сессий, публикация, автогенерация демонстраций из скриптов и место asciinema в рабочих процессах документации.
Установка и первая запись за минуту
Ставится пакет из репозитория дистрибутива: apt install asciinema, либо через pipx install asciinema для свежей версии. Запуск элементарный: asciinema rec demo.cast открывает подшелл, в котором вы выполняете команды, а по выходу запись спрашивает, что с ней делать - сохранить, проиграть или отправить на asciinema.org. Формат .cast это JSON Lines: шапка с размерами терминала и последовательность событий с отметками времени, поэтому файл компактен и читаем.
Проигрывание локально: asciinema play demo.cast воспроизводит запись в текущем терминале, а флаг -s 2 ускоряет показ вдвое. Для проверки до публикации работает воспроизведение из файла напрямую, без загрузки никуда. Загрузка на asciinema.org требует связки аккаунта через asciinema auth, и дальше у записи появляется постоянный URL, который можно втиснуть в README или вики.
Параметры, которые стоит знать сразу: -t заголовок у записи, -i 2 ограничивает паузу между командами двумя секундами (очень полезно, иначе реальные затянувшиеся раздумья записываются честно и мучают зрителя), -c выполняет конкретную команду вместо интерактивного шелла, --overwrite перезаписывает файл без вопросов. С этим набором уже пишутся приличные демонстрации.
Подготовка к записи, как получить чистый кадр
Хорошая запись начинается до нажатия rec. Первое: уменьшите окно терминала до 80-100 колонок, тогда запись будет читабельна везде и не поедет по ширине статьи. Второе: простой промпт, меньше мерцающих элементов - PS1="\\$ " на время записи избавляет ленту от имени хоста и цветовых украшений, которые отвлекают. Третье: запасной чистый профиль без ваших алиасов; asciinema rec -c 'bash --noprofile --norc' даёт стерильный сеанс, где команды выполняются стандартно, как у любого читателя.
Четвёртое - клавиатурная гигиена: медленный набор читается лучше быстрого, а опечатки приходится править - это нормально, но для идеала репетируйте проход до записи. Пятое: не забудьте про asciinema play для контроля. Удивительно, сколько материала выбрасывают после первого же просмотра, зато итоговое качество при этом растёт в разы.
Публикация и встраивание в документацию
На asciinema.org у каждой записи есть встроенный плеер, который встраивается в страницу тегом script или картинкой-превью со ссылкой. Для внутренних вики распространён self-hosted вариант: плеер это статический JavaScript, в файле README достаточно ссылки на файл .cast рядом, и коллеги проигрывают его у себя командой asciinema play URL. Альтернативный путь - экспорт в SVG: asciinema-snapshot или svg-term превращают запись в анимированный SVG, который вставляется как картинка в GitHub README без внешнего хостинга.
Для командной базы знаний удобна дисциплина именования и каталогизации: записи хранятся вместе с документацией в git, называются по сценарию (upgrade-to-v2.cast), и в Markdown рядом есть трёхстрочное описание ситуации, в которой запись снимается заново при смене процедуры. Так архив демонстраций не гниёт, потому что устаревший пример обнаруживается по первой же рассинхронизации с реальностью.
Автогенерация демонстраций из скриптов
Лучшие записи не повторяются руками, а генерируются скриптом. Паттерн: bash-файл с командами дополняется паузами sleep и echo-комментариями, и затем asciinema rec -i 1 -c ./demo.sh фиксирует весь прогон один раз и навсегда. Перезапись новой версии это один запуск, а не вечер с терминалом. К такому сценарному делу прикладывается и ожидание реального вывода через expect-подобные утилиты: команда expect ожидает появления строки перед продолжением, и запись выглядит живой, а не нарезкой по таймеру.
Из этого же набора техник строятся обучающие курсы: лектор готовит сценарии заранее, а записи генерируются при каждом обновлении версии инструмента автоматически в CI. Материал остаётся актуальным без ручного труда, что для технической документации редкий и потому драгоценный случай.
Границы формата и безопасность
Формат текстовый, и это его ограничение тоже: TUI с псевдографикой записывается, но сложные полноэкранные программы с мерцанием иногда производят тяжёлые файлы; мышь не существует; и любая секретная информация, набранная в записи, воспроизводится каждым зрителем буквально. Поэтому перед публикацией записи бегло просматривают на предмет токенов, паролей и путей, которым не место в публичном доступе. Полезная привычка: записывать в отдельном чистом каталоге и в отдельном оболочечном сеансе, чтобы ничего лишнего не проскочило в кадр.
В остальном формат держится уже много лет, обратно совместим и переживает смены инструментов просмотра без потерь, что для технической документации, которую планируется читать годами, качество почти бесценное: текстовая запись не протухает, так как это просто текст.
Итог, когда стоит записывать экран
Сценарии, где asciinema незаменима, перечисляются быстро: онбординг-гайды по CLI-процедурам, демонстрация рабочего скрипта коллегам, снапшот сложного вывода диагностики, обучение работе с новым внутренним инструментом. Всё это становится легко копируемым, вечно хранимым и удобно встраиваемым в Markdown-мира документации. Команда recording + ссылка в вики это пять минут работы, которые окупаются каждым новым человеком в команде, и по соотношению вложений к пользе asciinema до сих пор остаётся одним из самых верных приобретений в инженерном ящике.
Редактирование записи, обрезка, сжатие, титры
Сырые записи почти всегда требуют редактуры, и это нормальный этап. Хвост с командой exit и задумчивой паузой обрезается фильтром по времени: строка событий в .cast это JSONL, и несложный скрипт обрезает всё после последней значимой команды. Утилита asciinema сама предлагает удобства: команда cat с параметрами позволяет конвертировать между версиями формата, а сторонние скрипты убирают управляющие последовательности пагинаторов и скроллбэка, которые захламляют ленту. Для титров в самой записи вставляются события вывода текста - это тоже данные в том же формате.
Вторая задача редактуры - ускорение: паузы между командами реального человека редко представляют интерес, и фильтр, зажимающий любую паузу до секунды, кардинально ускоряет просмотр. Многие тренировочные касты после такой нормировки сокращаются из пятнадцати минут в четыре, и внимание зрителя наконец-то доживает до конца.
Встраивание в README и CI-регенерацию
Публикация в документации имеет три популярных подхода. Прямая ссылка на asciinema.org удобна для блогов и статей, где читателя ведут на красивый плеер. Встроенный плеер на своём сайте это статическая связка asciinema-player и .cast-файла рядом; работает без внешних зависимостей. Третий путь - анимированный SVG, который GitHub показывает прямо в README: файл генерируется из записи, вставляется как обычное изображение, и клик по нему ведёт на полную сессию. Для вики-корп это лучший баланс простоты и автономности.
Чтобы демонстрации не гнили, их регенерируют автоматически: скрипт demo.sh лежит рядом с документацией, и CI-задача при изменении версии инструмента переснимает запись. Такое поддержание в актуальности обычно удивляет: документация по CLI живёт точно столько, сколько живёт код, потому что это тот же самый код - сценарий записи и есть воспроизводимый артефакт. Команды, перешедшие на эту дисциплину, навсегда забывают про устаревшие скриншоты.
Практические правила хорошего вкуса при записи
Сводится всё к нескольким пунктам. Пишите медленно, комментируйте каждую нетривиальную команду выводимой строкой с пояснением, чтобы каст понимался без звука. Не пишите паролей; если аутентификация нужна, используйте учебный контур с фиктивным секретом, который после записи немедленно меняется. Один кадр на одну идею: лучше три коротких записи под отдельные задачи, чем сорокаминутный фильм. И держите размеры окна консервативными: запись в терминале на 240 колонок нечитабельна наполовину устройств вашей аудитории.
Asciinema внутри процесса разработки
Выход за пределы документации неожиданно приятен: баг-репорт с приложенным .cast воспроизводит проблему один в один, включая все промежуточные есть у всякой больной ситуации, и экономит часы переписки. Ревьюр сложных операций может смотреть запись вместо видеовстречи. Наставник видит руки стажёра и указывает на мелкие ошибки дословно, а не приблизительно. Инструмент редко рекламируется как помощник онбординга и поддержки, но именно там его ценность проявляется ярче всего - там, где точность важнее красоты.
Замыкая тему: установите asciinema сегодня, запишите один реальный сценарий из вашей текущей работы и положите его в вики. Через месяц удивитесь, как обходились без этого раньше - особенно в ту минуту, когда коллега вместо вопроса пришлёт вам просто ссылку на свою готовую запись проблемы, готовую к тому, чтобы её смотрели, копировали и понимали.
Типичные сценарии применения в инфраструктурной команде
Закрепим тему списком задач, где asciinema меняет правила игры. Первое - обучающие маршруты: новый инженер получает серию коротких записей о подъёме стенда, перекатке релиза и работе с резервной копией, и каждая запись копируема в свою консоль дословно. Второе - документирование аварийных процедур: восстановление из снапшота, сброс зависшей реплики, смена ключей - всё это записывается один раз в спокойной обстановке, чтобы в стрессовой уже не импровизировать на публику. Третье - демонстрация багов: короткая запись ситуации экономит часы переписки и делает репорт воспроизводимым.
Четвёртое - показ внутренних инструментов: консольный хэлпер команды с записью демо-сессии воспринимается новичком мгновенно, в отличие от README на сорок строк. Пятое - культурная привычка: записывать полезные терминальные открытия сразу по факту, пока горячо. Собранный таким образом архив записей становится самым читаемым разделом внутренней базы знаний, потому что он состоит из реальных действий реальных людей, а не из проповедей абстрактного характера. И это финальный аргумент: asciinema делает документацию честной, и честность здесь начинается с того, что нажать можно ровно то же, что и написано.
Напоследок о формате и его долговечности
Формат .cast пережил несколько мажорных ревизий, оставаясь читаемым JSON lines, и записи десятилетней давности открываются современным плеером без конвертации. Это редкое свойство в мире технических артефактов, которое стоит взвесить в момент выбора: инвестируя вечер в записи процедур, вы вкладываетесь в материал, который проживёт дольше половины инструментов, которые он документирует. А чтобы ваша компания точно не забыла эти скромные файлы, положите их туда, где живут остальные решения - рядом с кодом, под версионным контролем, и тогда любая свежая редакция процедуры будет синхронно сопровождаться свежей записью.
Такой подход к терминальным записям рано или поздно окажется в каждой зрелой команде: просто сделайте шаг первым и предложите демонстрацию вместо скринкаста при следующей удобной возможности.
И это решение точно не станет тем решением, о котором вы пожалеете.
Всем хороших записей и быстрых ответов.
Пусть ваши записи выручат коллег не один раз.