How to Record a Terminal GIF

Step-by-step guide to recording terminal sessions as GIF animations using VHS, asciinema, and AgentGIF CLI.

1. 전제 조건

터미널 GIF를 녹화하려면 다음이 필요합니다:

VHS — a terminal recorder by Charm that converts scripted terminal sessions into GIFs
ttyd — 터미널 웹 서버 (VHS 의존성, macOS에서 자동 설치)
ffmpeg — 비디오 인코딩용 (macOS에서 자동 설치)

VHS는 키 입력, 명령어, 타이밍을 설명하는 .tape 파일을 읽어 가상 터미널에서 해당 동작을 재생하고 출력을 GIF로 캡처합니다.

2. VHS 설치

플랫폼	설치 명령어
macOS	`brew install vhs`
Ubuntu/Debian	`sudo mkdir -p /etc/apt/keyrings && curl -fsSL https://repo.charm.sh/apt/gpg.key \| sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg && echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" \| sudo tee /etc/apt/sources.list.d/charm.list && sudo apt update && sudo apt install vhs`
Arch Linux	`yay -S vhs`
Go	`go install github.com/charmbracelet/vhs@latest`

설치 확인:

vhs --version

3. Tape 파일 만들기

tape 파일은 VHS에게 무엇을 입력할지, 언제 기다릴지, 어떤 설정을 사용할지 알려주는 일반 텍스트 스크립트입니다. demo.tape라는 파일을 만드세요:

Output demo.gif
Set Shell "bash"
Set FontSize 16
Set Width 1000
Set Height 580
Set Theme "Catppuccin Mocha"

Type "echo 'Hello, world!'"
Enter
Sleep 2s

Type "ls -la"
Enter
Sleep 3s

핵심 명령어

명령어	설명	예시
`Output`	출력 파일 경로 설정	`Output "demo.gif"`
`Type`	텍스트 입력 (키 입력 시뮬레이션)	`Type "git status"`
`Enter`	Enter 누르기	`Enter`
`Sleep`	지정된 시간 동안 대기	`Sleep 2s`
`Ctrl+C`	키보드 단축키 전송	`Ctrl+C`
`Hide`	녹화 중지 (설정용)	`Hide`
`Show`	녹화 재개	`Show`

4. 설정 구성

Type 명령어보다 앞에 tape 파일 상단에 Set 명령어를 넣으세요.

AgentGIF 권장 설정

Set Shell "zsh"
Set FontSize 15
Set Width 1000
Set Height 580
Set Padding 20
Set Theme "Catppuccin Mocha"
Set TypingSpeed 50ms
Set CursorBlink false

모든 사용 가능한 설정

설정	기본값	설명
`Shell`	`"bash"`	사용할 셸 (bash, zsh, fish, sh)
`FontSize`	`14`	픽셀 단위 폰트 크기
`Width`	`800`	픽셀 단위 터미널 너비
`Height`	`600`	픽셀 단위 터미널 높이
`Padding`	`0`	터미널 주위 여백
`Theme`	`"default"`	Color theme (see theme gallery)
`TypingSpeed`	`50ms`	키 입력 사이 지연
`Framerate`	`50`	GIF 초당 프레임
`PlaybackSpeed`	`1`	재생 속도 배율
`CursorBlink`	`true`	깜빡이는 커서 표시
`LetterSpacing`	`0`	추가 자간
`LineHeight`	`1.0`	줄 높이 배율

테마

VHS에는 44개의 내장 테마가 포함됩니다. 개발자 문서에서 인기 있는 선택:

테마	스타일
Catppuccin Mocha	따뜻한 다크 (파스텔 악센트)
Dracula	다크 퍼플
Tokyo Night	파란빛 다크
Nord	북극 블루
One Dark	Atom에서 영감 받은 다크
Solarized Dark	따뜻한 톤의 클래식 다크
Monokai	Sublime Text에서 영감 받은

실시간 미리보기로 모든 테마 탐색: 테마 갤러리.

5. GIF 녹화

vhs demo.tape

VHS는 헤드리스 브라우저를 열고 tape를 재생하며 GIF를 저장합니다. 일반적인 녹화는 10-30초가 걸립니다.

업로드 전 미리보기:

# macOS
open demo.gif

# Linux
xdg-open demo.gif

6. 파일 크기 최적화

AgentGIF은 최대 10 MB의 GIF를 허용하지만 작은 파일이 더 빠르게 로드됩니다. GIF 크기를 줄이는 팁:

기법	효과
크기 줄이기 (`Width 800`)	상당함 — 너비를 절반으로 줄이면 파일 크기가 1/4로 줄어듦
프레임레이트 낮추기 (`Framerate 30`)	보통 — 프레임을 40% 줄임
짧은 녹화	상당함 — 5-15초를 목표로 하세요
`PlaybackSpeed 1.5` 사용	보통 — 총 프레임 수 감소
커서 깜빡임 비활성화 (`CursorBlink false`)	작음 — 고유 프레임 수 감소
단색 배경 (투명도 사용 금지)	작음 — GIF 압축 향상

품질과 크기의 최적 균형을 위해 위의 권장 설정은 10초 녹화에서 약 100-300 KB의 GIF를 생성합니다.

7. AgentGIF에 업로드

CLI를 통한 업로드 (가장 빠름):

agentgif upload demo.gif \
  --title "Git Interactive Rebase" \
  --command "git rebase -i HEAD~3" \
  --tags git,rebase \
  --open

Or upload via the web interface — drag and drop the GIF file.

cast 파일을 포함하면 AI 에이전트 레이어가 활성화됩니다:

agentgif upload demo.gif --cast demo.cast --title "My Demo"

8. 고급 Tape 기능

설정을 위한 Hide/Show

녹화 없이 설정 명령어를 실행하려면 Hide/Show를 사용하세요:

Hide
Type "cd /tmp/demo-project"
Enter
Type "mkdir -p src"
Enter
Show

# Now recording starts
Type "ls -la"
Enter
Sleep 2s

다중 출력 형식

VHS는 여러 형식을 동시에 출력할 수 있습니다:

Output demo.gif
Output demo.mp4
Output demo.webm

환경 변수

Set Shell "bash"
Type "export PS1='$ '"
Enter
Hide
Sleep 500ms
Show

키보드 단축키

Ctrl+C     # Cancel current command
Ctrl+L     # Clear screen
Ctrl+D     # EOF / exit
Tab        # Tab completion
Up         # Previous command
Escape     # Escape key

9. 대안 녹화 도구

도구	출력	장점	단점
VHS	GIF, MP4, WebM	스크립트 방식, 재현 가능, 테마	설정 필요
asciinema	.cast	실시간 녹화, 작은 파일	GIF 출력 없음 (변환 필요)
Terminalizer	GIF	실시간 녹화, YAML 설정	큰 파일 크기
Peek	GIF, WebM	GUI 화면 레코더	터미널 특화 아님

스크립트 방식 데모(재현 가능, 버전 관리 가능)에는 VHS를, 실시간 녹화에는 asciinema + VHS 변환을 권장합니다.

← 모든 가이드 · GitHub README에 GIF 임베드 →