¿Qué hace cli-anything-iterm2?
Harness CLI con estado para iTerm2. Controla un proceso vivo de iTerm2 a través de la API de Python de iTerm2 sobre WebSocket.
Requisitos Previos
- macOS + iTerm2 en ejecución:
brew install --cask iterm2 - API de Python habilitada: iTerm2 → Preferencias → General → Magia → Activar API de Python
- Instalar:
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 app, instantánea del espacio de trabajo, gestión de contexto, variables a nivel de app, diálogos modales, paneles de archivos |
window | Crear, listar, cerrar, redimensionar, maximizar ventanas |
tab | Crear, listar, cerrar, activar pestañas; navegar 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 del perfil, listar/aplicar presets 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 |
Orientarse 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 los contenidos completos de la pantalla para cada panel:
cli-anything-iterm2 --json app snapshot
Devuelve el nombre, directorio actual, proceso en primer plano, etiqueta user.role y la última línea visible de salida para cada sesión en todas las ventanas.
Convención de nombres — etiqueta los paneles al configurar un espacio de trabajo para poder encontrarlos después:
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 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 con múltiples paneles — 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 único aspecto concreto (~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 confiable send→wait→read |
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 app, diálogos modales, paneles de archivos |
references/profile-pref.md | Lista/obtiene perfiles y presets, lee/escribe preferencias, atajos de pref 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, creación de ventana, set-visible) |
references/tmux-guide.md | Flujo de trabajo completo de tmux -CC, mapeo panel→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 app, preferencias, errores |
Modo REPL
Ejecuta sin argumentos para un REPL interactivo que mantiene el contexto entre comandos:
cli-anything-iterm2