O que cli-anything-iterm2 faz?
Harness de linha de comando stateful para iTerm2. Controla um processo iTerm2 ativo via API Python do iTerm2 sobre WebSocket.
Pré-requisitos
- macOS + iTerm2 em execução:
brew install --cask iterm2 - API Python habilitada: iTerm2 → Preferências → Geral → Mágica → Habilitar API Python
- Instalação:
pip install cli-anything-iterm2(oupip install -e .a partir do código-fonte)
Sintaxe Básica
cli-anything-iterm2 [--json] <grupo> <comando> [OPÇÕES] [ARGUMENTOS]
Use sempre --json para saída legível por máquina (obrigatório para uso por agente).
Grupos de Comandos
| Grupo | Propósito |
|---|---|
app | Status do aplicativo, snapshot do workspace, gerenciamento de contexto, variáveis do app, diálogos modais, painéis de arquivo |
window | Criar, listar, fechar, redimensionar, maximizar janelas |
tab | Criar, listar, fechar, ativar abas; navegar entre painéis divididos por direção |
session | Enviar texto, injetar bytes brutos, ler tela, scrollback completo, dividir painéis, detecção de prompt |
profile | Listar perfis, obter detalhes do perfil, listar/aplicar predefinições de cores |
arrangement | Salvar e restaurar layouts de janela |
tmux | Integração completa com tmux -CC: inicialização, conexões, janelas, comandos |
broadcast | Sincronizar teclas entre painéis via domínios de broadcast |
menu | Invocar qualquer item de menu do iTerm2 programaticamente |
pref | Ler/escrever preferências globais do iTerm2; listar todas as chaves válidas; configurações de tmux |
Orientando-se em um Workspace Existente
Use app snapshot ao chegar em uma sessão com painéis existentes e precisar entender o que está rodando sem ler o conteúdo completo da tela de cada painel:
cli-anything-iterm2 --json app snapshot
Retorna nome, diretório atual, processo em foreground, rótulo user.role e a última linha de saída visível para todas as sessões em todas as janelas.
Convenção de nomenclatura — rotule os painéis ao configurar um workspace para encontrá-los depois:
cli-anything-iterm2 session set-var user.role "api-server"
cli-anything-iterm2 session set-var user.role "log-tail"
cli-anything-iterm2 session set-var user.role "editor"
app snapshot exibirá esses papéis junto com o processo e o caminho, dando a você uma visão completa em uma única chamada.
Workflow Típico de Agente
# 1. Orientar — snapshot de cada sessão: nome, caminho, processo, papel, última linha de saída
cli-anything-iterm2 --json app snapshot
# 2. Estabelecer contexto (salva IDs de janela/aba/sessão para comandos subsequentes)
cli-anything-iterm2 app current
# 3. Interagir — não é necessário --session-id após definir o contexto
cli-anything-iterm2 session send "git status"
cli-anything-iterm2 --json session scrollback --tail 200 --strip
# 4. Criar um workspace com múltiplos painéis — rotule os painéis para que o snapshot os identifique depois
cli-anything-iterm2 session split --vertical --use-as-context
cli-anything-iterm2 session send "python3 -m http.server 8000"
cli-anything-iterm2 session set-var user.role "http-server"
Arquivos de Referência
Leia apenas o que a tarefa exigir — cada arquivo trata de um único assunto (~10–30 linhas):
| Arquivo | Leia quando precisar... |
|---|---|
references/session-io.md | Enviar texto, injetar bytes, ler tela/scrollback, obter seleção |
references/session-control.md | Dividir painéis, ativar/fechar sessões, redimensionar, renomear, variáveis de sessão |
references/session-shell-integration.md | wait-prompt, wait-command-end, get-prompt; padrão confiável send→wait→read |
references/layout-window-tab.md | Criar/fechar/redimensionar janelas e abas, navegar entre painéis divididos |
references/layout-arrangement.md | Salvar e restaurar layouts de janela |
references/app-context.md | Snapshot (orientação), status, gerenciamento de contexto, variáveis do app, diálogos modais, painéis de arquivo |
references/profile-pref.md | Listar/obter perfis, predefinições, ler/escrever preferências, atalhos de pref tmux |
references/broadcast-menu.md | Transmitir teclas para múltiplos painéis, invocar itens de menu |
references/tmux-commands.md | Todos os comandos CLI do tmux (inicialização, enviar, abas, criar janela, set-visible) |
references/tmux-guide.md | Workflow completo do tmux -CC, mapeamento painel→ID de sessão |
references/json-session.md | Esquemas --json para sessão, janela, aba, tela, scrollback, injeção |
references/json-tmux-app.md | Esquemas --json para tmux, diálogos do app, preferências, erros |
Modo REPL
Execute sem argumentos para um REPL interativo que mantém o contexto entre comandos:
cli-anything-iterm2