How to Record a Terminal GIF

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

1. Pré-requisitos

Para gravar GIFs de terminal, você precisa de:

VHS — a terminal recorder by Charm that converts scripted terminal sessions into GIFs
ttyd — um servidor web de terminal (dependência do VHS, instalado automaticamente no macOS)
ffmpeg — para codificação de vídeo (instalado automaticamente no macOS)

O VHS funciona lendo um arquivo .tape que descreve teclas pressionadas, comandos e tempo — depois reproduz essas ações em um terminal virtual e captura a saída como GIF.

2. Instalar VHS

Plataforma	Comando de Instalação
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`

Verifique a instalação:

vhs --version

3. Criar um Arquivo Tape

Um arquivo tape é um script em texto simples que diz ao VHS o que digitar, quando aguardar e quais configurações usar. Crie um arquivo chamado 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

Comandos Principais

Comando	Descrição	Exemplo
`Output`	Definir o caminho do arquivo de saída	`Output "demo.gif"`
`Type`	Digitar texto (simula teclas pressionadas)	`Type "git status"`
`Enter`	Pressionar Enter	`Enter`
`Sleep`	Aguardar uma duração	`Sleep 2s`
`Ctrl+C`	Enviar atalho de teclado	`Ctrl+C`
`Hide`	Parar gravação (para configuração)	`Hide`
`Show`	Retomar gravação	`Show`

4. Configurar Definições

Coloque os comandos Set no topo do seu arquivo tape, antes de qualquer comando Type.

Configurações Recomendadas para 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

Todas as Configurações Disponíveis

Configuração	Padrão	Descrição
`Shell`	`"bash"`	Shell a usar (bash, zsh, fish, sh)
`FontSize`	`14`	Tamanho da fonte em pixels
`Width`	`800`	Largura do terminal em pixels
`Height`	`600`	Altura do terminal em pixels
`Padding`	`0`	Preenchimento ao redor do terminal
`Theme`	`"default"`	Color theme (see theme gallery)
`TypingSpeed`	`50ms`	Atraso entre teclas pressionadas
`Framerate`	`50`	Frames por segundo do GIF
`PlaybackSpeed`	`1`	Multiplicador de velocidade de reprodução
`CursorBlink`	`true`	Mostrar cursor piscante
`LetterSpacing`	`0`	Espaçamento adicional entre letras
`LineHeight`	`1.0`	Multiplicador de altura de linha

Temas

O VHS vem com 44 temas integrados. Escolhas populares para documentação de desenvolvedor:

Tema	Estilo
Catppuccin Mocha	Escuro quente (acentos pastéis)
Dracula	Roxo escuro
Tokyo Night	Escuro com tonalidade azul
Nord	Azul ártico
One Dark	Escuro inspirado no Atom
Solarized Dark	Escuro clássico com tons quentes
Monokai	Inspirado no Sublime Text

Navegue por todos os temas com pré-visualizações ao vivo: Galeria de Temas.

5. Gravar o GIF

vhs demo.tape

O VHS abre um navegador headless, reproduz o tape e salva o GIF. A gravação típica leva de 10 a 30 segundos.

Pré-visualizar antes de enviar:

# macOS
open demo.gif

# Linux
xdg-open demo.gif

6. Otimizar Tamanho do Arquivo

O AgentGIF aceita GIFs de até 10 MB, mas arquivos menores carregam mais rápido. Dicas para manter o tamanho do GIF pequeno:

Técnica	Impacto
Reduzir dimensões (`Width 800`)	Significativo — reduzir a largura pela metade reduz o tamanho do arquivo a um quarto
Framerate menor (`Framerate 30`)	Moderado — reduz os frames em 40%
Gravação mais curta	Significativo — busque de 5 a 15 segundos
Usar `PlaybackSpeed 1.5`	Moderado — menos frames no total
Desativar cursor piscante (`CursorBlink false`)	Pequeno — menos frames únicos
Fundo sólido (evitar transparência)	Pequeno — melhor compressão de GIF

Para o melhor equilíbrio entre qualidade e tamanho, as configurações recomendadas acima produzem GIFs de cerca de 100-300 KB para uma gravação de 10 segundos.

7. Enviar para o AgentGIF

Enviar via CLI (mais rápido):

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.

Incluir um arquivo cast habilita a camada de agente de IA:

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

8. Recursos Avançados de Tape

Ocultar/Mostrar para Configuração

Use Hide/Show para executar comandos de configuração sem gravá-los:

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

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

Múltiplos Formatos de Saída

O VHS pode gerar múltiplos formatos simultaneamente:

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

Variáveis de Ambiente

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

Atalhos de Teclado

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

9. Ferramentas Alternativas de Gravação

Ferramenta	Saída	Prós	Contras
VHS	GIF, MP4, WebM	Scriptado, reproduzível, temas	Requer configuração
asciinema	.cast	Gravação ao vivo, arquivos pequenos	Sem saída GIF (precisa de conversão)
Terminalizer	GIF	Gravação ao vivo, configuração YAML	Tamanhos de arquivo grandes
Peek	GIF, WebM	Gravador de tela GUI	Não específico para terminal

Recomendamos VHS para demos scriptadas (reproduzível, versionável) e asciinema + conversão VHS para gravações ao vivo.

← Todos os Guias · Incorporar GIFs em GitHub README →