cli-anything-iterm2
Herramienta CLI con estado para iTerm2. Controla un proceso iTerm2 en vivo mediante la API de Python de iTerm2 a través de WebSocket.
Requisitos previos
- macOS + iTerm2 en ejecución:
brew install --cask iterm2 - API de Python habilitada: iTerm2 → Preferencias → General → Magia → Habilitar API de Python
- Instalación:
pip install cli-anything-iterm2(opip install -e .desde el código fuente)
Sintaxis básica
cli-anything-iterm2 [--json] <grupo> <comando> [OPCIONES] [ARGUMENTOS]
Usa siempre --json para obtener salida legible por máquina (requerido para uso con agentes).
Grupos de comandos
| Grupo | Propósito |
|---|---|
app | Estado de la aplicación, instantánea del espacio de trabajo, gestión de contexto, variables de la aplicación, diálogos modales, paneles de archivos |
window | Crear, listar, cerrar, redimensionar ventanas; pantalla completa |
tab | Crear, listar, cerrar, activar pestañas; navegar entre paneles divididos por dirección |
session | Enviar texto, inyectar bytes sin procesar, leer pantalla, scrollback completo, dividir paneles, detección de prompt |
profile | Listar perfiles, obtener detalles de perfil, listar/aplicar preajustes de color |
arrangement | Guardar y restaurar diseños de ventanas |
tmux | Integración completa con tmux -CC: arranque, conexiones, ventanas, comandos |
broadcast | Sincronizar pulsaciones de teclas entre paneles mediante dominios de difusión |
menu | Invocar cualquier elemento del menú de iTerm2 de forma programática |
pref | Leer/escribir preferencias globales de iTerm2; listar todas las claves válidas; ajustes de tmux |
Orientación en un espacio de trabajo existente
Usa app snapshot cuando llegues a una sesión con paneles existentes y necesites entender qué se está ejecutando sin leer el contenido completo de la pantalla de cada panel:
cli-anything-iterm2 --json app snapshot
Devuelve el nombre, directorio actual, proceso en primer plano, etiqueta user.role y última línea de salida visible para cada sesión en todas las ventanas.
Convención de nomenclatura: etiqueta los paneles al configurar un espacio de trabajo para que puedas encontrarlos más tarde:
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 mostrará estos roles junto con el proceso y la ruta, dándote una imagen completa en una sola llamada.
Flujo de trabajo típico para agentes
# 1. Orientarse — instantánea de cada sesión: nombre, ruta, proceso, rol, última línea de salida
cli-anything-iterm2 --json app snapshot
# 2. Establecer contexto (guarda los IDs de ventana/pestaña/sesión para comandos posteriores)
cli-anything-iterm2 app current
# 3. Interactuar — no se necesita --session-id una vez establecido el contexto
cli-anything-iterm2 session send "git status"
cli-anything-iterm2 --json session scrollback --tail 200 --strip
# 4. Crear un espacio de trabajo multipanel — etiqueta los paneles para que snapshot los identifique después
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"
Archivos de referencia
Lee solo lo que la tarea requiera: cada archivo cubre un aspecto único y específico (~10–30 líneas):
| Archivo | Léelo cuando necesites... |
|---|---|
references/session-io.md | Enviar texto, inyectar bytes, leer pantalla/scrollback, obtener selección |
references/session-control.md | Dividir paneles, activar/cerrar sesiones, redimensionar, renombrar, variables de sesión |
references/session-shell-integration.md | wait-prompt, wait-command-end, get-prompt; patrón fiable enviar→esperar→leer |
references/layout-window-tab.md | Crear/cerrar/redimensionar ventanas y pestañas, navegar paneles divididos |
references/layout-arrangement.md | Guardar y restaurar diseños de ventanas |
references/app-context.md | Snapshot (orientación), estado, gestión de contexto, variables de la aplicación, diálogos modales, paneles de archivos |
references/profile-pref.md | Lista de perfiles/obtener/preajustes, lectura/escritura de preferencias, accesos directos de preferencias de tmux |
references/broadcast-menu.md | Transmitir pulsaciones de teclas a múltiples paneles, invocar elementos del menú |
references/tmux-commands.md | Todos los comandos CLI de tmux (arranque, envío, pestañas, crear-ventana, set-visible) |
references/tmux-guide.md | Flujo de trabajo completo de tmux -CC, mapeo de panel a ID de sesión |
references/json-session.md | Esquemas --json para sesión, ventana, pestaña, pantalla, scrollback, inyección |
references/json-tmux-app.md | Esquemas --json para tmux, diálogos de la aplicación, preferencias, errores |
Modo REPL
Ejecuta sin argumentos para un REPL interactivo que mantiene el contexto entre comandos:
cli-anything-iterm2