Referencia de la CLI

La CLI de Herdr habla con el servidor en marcha a través de la misma API de socket local que usan las integraciones y los agentes.

La mayoría de los comandos imprimen respuestas JSON, para automatizar con scripts de forma determinista.

Lanzar y estado

herdr                         # lanza la sesión por defecto o se conecta a ella
herdr --remote workbox        # se conecta por SSH, con los atajos locales
herdr --default-config        # imprime la configuración por defecto
herdr update                  # descarga e instala desde el canal configurado
herdr completion zsh          # genera un script de autocompletado para zsh
herdr channel show            # imprime stable o preview
herdr channel set preview     # pasa a las compilaciones preliminares
herdr channel set stable      # devuelve una instalación directa a stable
herdr --version               # imprime la versión

Opciones de lanzamiento y actualización:

• Añade --session <nombre> para usar una sesión con nombre en lugar de la sesión por defecto.
• Añade --remote-keybindings server a la conexión remota para usar los atajos del servidor en lugar de los locales.
• El traspaso en caliente experimental requiere --handoff explícito en herdr --remote o herdr update. No es la vía normal de configuración ni de conexión; mira Actualizar.

Comandos de estado:

herdr status
herdr status server
herdr status client

Comandos del esquema de la API:

herdr api schema
herdr api schema --json
herdr api schema --output herdr-api.schema.json

herdr api schema imprime un resumen breve del esquema del protocolo de socket incluido en el binario instalado. Usa --json para el documento JSON Schema completo, o --output RUTA para escribirlo en un fichero.

Máquinas SSH guardadas

herdr machine list
herdr machine add workbox --label "Máquina de compilación"
herdr machine rename <id-de-perfil> --label "Nombre nuevo"
herdr machine disable <id-de-perfil>
herdr machine enable <id-de-perfil>
herdr machine remove <id-de-perfil>

Por defecto, machine add usa la sesión remota por defecto. Añade --remote-session <nombre> solo para una sesión con nombre. machine list acepta un --json opcional para scripts. Mira Conectar máquinas para la guía completa de configuración y conexión.

machine add comprueba las capacidades de la instalación remota, instala o actualiza con aprobación solo cuando hace falta, y arranca el servidor en segundo plano de la sesión pedida antes de guardar. Las versiones compatibles no tienen que coincidir. Ejecuta la configuración en una terminal interactiva cuando haga falta aprobar una instalación o un reinicio; una configuración fallida o cancelada no guarda el perfil. Reemplazar un servidor en marcha requiere aprobación explícita, con No como respuesta por defecto, y para los procesos de sus paneles. machine add nunca activa el traspaso experimental de forma implícita.

Los cambios se aplican automáticamente a los clientes locales abiertos, normalmente en un segundo. Las máquinas añadidas o activadas se conectan en segundo plano; renombrar no reconecta. Eliminar o desactivar desconecta solo esa máquina y deja sus sesiones remotas en marcha. Eliminar la máquina que estás viendo te devuelve a la local, o muestra la local como no disponible hasta que se reconecte. Cada perfil guarda en el estado del cliente un ID opaco, la etiqueta, el destino SSH, la sesión remota explícita y el estado de activación. Herdr no guarda contraseñas, claves privadas ni otras credenciales SSH.

Las conexiones y reconexiones automáticas no son interactivas. Si una clave de host, una contraseña, la contraseña de una clave, un paso de MFA, una instalación, una actualización o un reinicio necesitan aprobación, la máquina muestra Atención en vez de abrir una pregunta oculta. Ejecuta el comando independiente que imprime Herdr, como herdr --remote workbox, para completar esa configuración en primer plano, y reinicia el cliente. Incluye --session <nombre> solo cuando el perfil apunte a una sesión con nombre.

Los IDs de espacio de trabajo, pestaña y panel, y los nombres de agente, pertenecen a un solo servidor. Seleccionar una máquina en la interfaz no cambia el destino de los comandos de la CLI. Usa el prefijo global --machine <etiqueta-o-id> para dirigir comandos de la API a una máquina SSH guardada:

herdr --machine "Máquina de compilación" agent list
herdr --machine <id-de-perfil> pane list
herdr --machine "Máquina de compilación" agent prompt w1:p1 "revisa este cambio"
herdr --machine "Máquina de compilación" worktree create --cwd /srv/project --branch review

El selector debe coincidir con el ID de un perfil guardado y activado, o con una etiqueta única (distinguiendo mayúsculas), no con un nombre de host SSH cualquiera. Se usa la sesión remota guardada; combinar --machine con --session o --remote es un error. Sin el prefijo, los comandos conservan su comportamiento local de sesión y socket.

Los comandos admitidos son workspace, worktree, tab, pane, notification, agent (salvo attach y el explain --file local), api snapshot, status server y los comandos de plugin respaldados por la API (link, unlink, enable, disable, list, action, log, pane). Los comandos de servidor admiten stop, reload-config, agent-manifests y reload-agent-manifests. No se reenvían los comandos locales de instalación y configuración, la instalación de plugins, la gestión de sesiones ni la conexión interactiva a terminales.

Las peticiones y respuestas viajan por la API JSON sobre SSH no interactivo; los datos de la API no se interpolan en el comando de shell de SSH. No hace falta tener la interfaz abierta, y el puente nunca instala, arranca ni reinicia un servidor. Actualiza la CLI local y la instalación remota de Herdr para que admitan el reenvío a máquinas, y mantén compatible el protocolo de la API del servidor remoto en marcha. La autenticación, las máquinas no disponibles y las versiones incompatibles fallan sin recurrir a la máquina local. Las peticiones no se reintentan automáticamente tras un fallo de conexión.

Los IDs de panel locales no los heredan los comandos remotos. Usa IDs remotos explícitos; --current no puede referirse al panel local desde el que se llama. Las rutas de worktree remotas deben ser absolutas, ~ o empezar por ~/ (se expanden en el servidor); las rutas para enlazar plugins deben ser absolutas. El prefijo apunta a una máquina cada vez; no incluye listados combinados ni enrutado a través de las conexiones de otra interfaz.

Autocompletado del shell

herdr completion zsh
herdr completions zsh
herdr completion bash
herdr completion fish
herdr completion powershell
herdr completion elvish

completion imprime el script por la salida estándar. completions es un alias. Para una sesión temporal de zsh, carga el script directamente:

source <(herdr completion zsh)

Para una configuración persistente de zsh, escribe la función _herdr generada en algún directorio de tu fpath antes de que se ejecute compinit:

mkdir -p ~/.zfunc
herdr completion zsh > ~/.zfunc/_herdr

Y asegúrate de que tu .zshrc contiene:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit
compinit

Servidor

herdr server
herdr server stop
herdr server reload-config
herdr server agent-manifests [--json]
herdr server update-agent-manifests [--json]
herdr server reload-agent-manifests

herdr server ejecuta el servidor sin interfaz de forma explícita. Úsalo en instalaciones supervisadas o como servicio. reload-config aplica los ajustes recargables sin reiniciar los paneles. agent-manifests muestra las fuentes activas de los manifiestos de detección de agentes, las versiones remotas en caché y los resultados de la última actualización remota. update-agent-manifests descarga de inmediato las actualizaciones remotas de manifiestos, las recarga en el servidor en marcha e imprime el estado actualizado; pasa --json para la respuesta de estado en bruto. reload-agent-manifests recarga los manifiestos de detección en el servidor en marcha después de editar los ficheros locales.

Notificaciones

herdr notification show <título> [--body TEXTO] [--position top-left|top-right|bottom-left|bottom-right] [--sound none|done|request]

notification show usa la entrega configurada en [ui.toast]. --position solo afecta a los avisos dentro de Herdr. --sound es none por defecto; done y request reproducen los sonidos de terminado y de necesita atención solo cuando la notificación se muestra.

Sesiones

herdr session list [--json]
herdr session attach <nombre>
herdr session stop <nombre> [--json]
herdr session delete <nombre> [--json]

Usa default como nombre de sesión cuando necesites parar expresamente la sesión por defecto.

Espacios de trabajo

herdr workspace list
herdr workspace create [--cwd RUTA] [--label TEXTO] [--env CLAVE=VALOR] [--focus] [--no-focus]
herdr workspace get <workspace_id>
herdr workspace focus <workspace_id>
herdr workspace rename <workspace_id> <etiqueta>
herdr workspace report-metadata <workspace_id> --source ID [--token NOMBRE=VALOR] [--clear-token NOMBRE] [--seq N] [--ttl-ms N]
herdr workspace close <workspace_id> [--group]

Crea un espacio de trabajo sin robar el foco:

herdr workspace create --cwd ~/proyecto --label api --no-focus

Un espacio de trabajo es un proyecto o contexto de trabajo de nivel superior. Crearlo crea también su primera pestaña y su panel raíz. La respuesta JSON expone sus IDs como .result.workspace.workspace_id, .result.tab.tab_id y .result.root_pane.pane_id.

Worktrees

herdr worktree list [--workspace ID | --cwd RUTA] [--trust-repository]
herdr worktree create [--workspace ID | --cwd RUTA] [--branch NOMBRE] [--base REF] [--path RUTA] [--label TEXTO] [--focus] [--no-focus] [--trust-repository]
herdr worktree open [--workspace ID | --cwd RUTA] (--path RUTA | --branch NOMBRE) [--label TEXTO] [--focus] [--no-focus] [--trust-repository]
herdr worktree remove --workspace ID [--force] [--trust-repository]

Los worktrees son espacios de trabajo normales de Herdr con procedencia de una copia de Git. worktree create crea una copia de trabajo de Git, la abre como espacio de trabajo y la agrupa con el espacio de trabajo del repositorio padre. Si --branch nombra una rama local existente, Herdr la usa; si no, crea la rama a partir de --base o de HEAD. Sin --path, Herdr crea la copia en <worktrees.directory>/<repo>/<slug-de-la-rama>.

workspace close cierra solo el estado de Herdr. Cerrar un espacio de trabajo principal mientras hay espacios de worktree enlazados abiertos requiere --group; sin él, el comando deja el grupo abierto y devuelve workspace_group_close_required. Para borrar la copia, ejecuta worktree remove. Ejecuta git worktree remove, nunca borra la rama y requiere --force cuando Git rechaza una copia con cambios.

Git rechaza por defecto los repositorios que pertenecen a otro usuario. Si has verificado el repositorio por tu cuenta, pasa --trust-repository para confiar en su ruta resuelta solo en ese comando. Herdr no cambia tu configuración de Git.

Pestañas

herdr tab list [--workspace <workspace_id>]
herdr tab create [--workspace <workspace_id>] [--cwd RUTA] [--label TEXTO] [--env CLAVE=VALOR] [--focus] [--no-focus]
herdr tab get <tab_id>
herdr tab focus <tab_id>
herdr tab rename <tab_id> <etiqueta>
herdr tab close <tab_id>

Una pestaña es otra disposición de terminales dentro de un espacio de trabajo. Sin --workspace, tab create usa el espacio de trabajo activo y falla si no hay ninguno. Su respuesta JSON expone .result.tab.tab_id y .result.root_pane.pane_id. Cerrar la última pestaña de un espacio de trabajo cierra también el espacio de trabajo, como la acción de cerrar pestaña de la interfaz. Si confirm_close está activo y cerrar la pestaña cerraría también un grupo de worktree completo, tab close devuelve un error confirmation_required.

Con ui.confirm_close activo, la interfaz pide confirmación antes de cerrar la última pestaña de un espacio de trabajo desde un atajo o desde el menú de la pestaña. Los cierres normales por CLI o API siguen siendo inmediatos.

La creación de espacios de trabajo y pestañas, y la división de paneles, no cambian el foco por defecto. --focus selecciona la disposición nueva; --no-focus declara el valor por defecto de forma explícita. Sin --cwd, las terminales nuevas siguen la política terminal.new_cwd configurada, que por defecto sigue al panel o espacio de trabajo de origen. Cada --env CLAVE=VALOR añade o sustituye esa variable en el shell raíz nuevo.

Paneles

herdr pane list [--workspace <workspace_id>]
herdr pane current [--pane ID|--current]
herdr pane get <pane_id>
herdr pane layout [--pane ID|--current]
herdr pane process-info [--pane ID|--current]
herdr pane neighbor --direction left|right|up|down [--pane ID|--current]
herdr pane edges [--pane ID|--current]
herdr pane focus --direction left|right|up|down [--pane ID|--current]
herdr pane resize --direction left|right|up|down [--amount FLOAT] [--pane ID|--current]
herdr pane zoom [<pane_id>|--pane ID|--current] [--toggle|--on|--off]
herdr pane rename <pane_id> <etiqueta>|--clear
herdr pane input [<pane_id>|--pane ID|--current] --right-click herdr|pane
herdr pane split [<pane_id>|--pane ID|--current] --direction right|down [--ratio FLOAT] [--cwd RUTA] [--env CLAVE=VALOR] [--right-click herdr|pane] [--focus] [--no-focus]
herdr pane swap --direction left|right|up|down [--pane ID|--current]
herdr pane swap --source-pane ID --target-pane ID
herdr pane move <pane_id> --tab <tab_id> --split right|down [--target-pane ID] [--ratio FLOAT] [--focus|--no-focus]
herdr pane move <pane_id> --new-tab [--workspace ID] [--label TEXTO] [--focus|--no-focus]
herdr pane move <pane_id> --new-workspace [--label TEXTO] [--tab-label TEXTO] [--focus|--no-focus]
herdr pane close <pane_id>

En los comandos de panel que aceptan --current, Herdr usa el HERDR_PANE_ID del panel desde el que se llama cuando el comando corre dentro de un panel de Herdr. En pane split, un id de panel explícito o --pane ID divide ese panel. Si se omite el destino, divide el panel desde el que se llama cuando HERDR_PANE_ID está disponible, y si no, el panel enfocado. --current requiere un panel de origen y da error cuando HERDR_PANE_ID no está disponible. La respuesta de la división expone el ID del panel nuevo como .result.pane.pane_id.

pane input --right-click pane reenvía los gestos de clic derecho sin modificador a una aplicación del panel que gestione el ratón. herdr restaura el menú de panel por defecto. El clic derecho en el marco del panel sigue abriendo el menú de Herdr. pane split --right-click pane aplica la misma política al panel nuevo desde su creación.

Después de pane move, usa .result.move_result.pane.pane_id en los comandos posteriores. Un movimiento entre espacios de trabajo cambia el ID de panel cualificado por espacio de trabajo; el valor anterior queda en .result.move_result.previous_pane_id. El proceso en marcha conserva los HERDR_PANE_ID, HERDR_TAB_ID y HERDR_WORKSPACE_ID que tenía al lanzarse; Herdr conserva el ID de panel antiguo como alias de esa terminal, así que los comandos de panel con --current siguen resolviéndolo. Un nombre de agente vivo sigue a la terminal y sigue resolviéndose después del movimiento.

Leer la salida:

herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi] [--raw]
herdr pane read <pane_id> --source visible --ansi
herdr pane read <pane_id> --source recent-unwrapped --lines 120

pane read imprime directamente el texto UTF-8 de la terminal. Las secuencias ANSI se eliminan por defecto; usa --format ansi o --ansi para conservarlas cuando la fuente expone estilos. La fuente detection es siempre texto plano. En las fuentes recientes, --lines N selecciona las últimas N filas de terminal pintadas antes del desenvuelto opcional; sin él, las lecturas toman 80 filas por defecto. En visible y detection, omitir --lines devuelve la instantánea completa, e indicarlo conserva las últimas N líneas delimitadas por salto de línea. agent read usa el mismo comportamiento de salida y de líneas.

Enviar entrada:

herdr pane send-text <pane_id> <texto>
herdr pane send-keys <pane_id> <tecla> [tecla ...]
herdr pane run <pane_id> <comando>

<tecla> usa la sintaxis de combinaciones de Herdr: teclas imprimibles como a, teclas especiales como enter, tab, esc, backspace, left, right, up y down, combinaciones con modificadores como ctrl+h, control+j, alt+x y shift+tab, teclas de función como f1, y signos con nombre como minus, plus y backtick. Las formas antiguas C-c y c-c se aceptan como alias de ctrl+c. esc es la forma canónica; escape también se acepta.

pane run respeta el modo de pegado entre corchetes activo y envía el texto más Intro de forma atómica. Prefiérelo a send-text más send-keys Enter para comandos; las operaciones de envío separadas son de bajo nivel y no envían el comando.

Informar del estado de un agente desde ganchos propios:

herdr pane report-agent <pane_id> \
  --source ID \
  --agent ETIQUETA \
  --state idle|working|blocked|unknown \
  [--message TEXTO] \
  [--seq N] \
  [--agent-session-id ID] \
  [--agent-session-path RUTA]

herdr pane report-agent-session <pane_id> \
  --source ID \
  --agent ETIQUETA \
  [--seq N] \
  [--agent-session-id ID] \
  [--agent-session-path RUTA] \
  [--session-start-source FUENTE]

herdr pane release-agent <pane_id> \
  --source ID \
  --agent ETIQUETA \
  [--seq N]

report-agent-session actualiza la identidad de sesión nativa sin informar del estado de ciclo de vida. release-agent termina la autoridad de ciclo de vida de esa fuente cuando su proceso de agente sale.

pane get, pane list, agent get y agent list incluyen un objeto de solo lectura agent_session cuando una integración oficial ha informado de una referencia de sesión nativa. Si no hay ninguna guardada, el campo se omite.

Esos comandos incluyen foreground_cwd cuando Herdr puede resolver el directorio del proceso en primer plano que controla el panel. El campo cwd sigue siendo el directorio del panel o espacio de trabajo que se usa en las etiquetas y en el comportamiento de seguir el directorio.

pane get y pane list incluyen scroll cuando hay métricas de desplazamiento de la terminal. scroll.offset_from_bottom == 0 significa que el panel está al final de su historial.

Informar de metadatos de panel solo visuales, sin apropiarse del estado semántico:

herdr pane report-metadata <pane_id> \
  --source ID \
  [--agent ETIQUETA] \
  [--applies-to-source ID] \
  [--title TEXTO|--clear-title] \
  [--display-agent TEXTO|--clear-display-agent] \
  [--state-label ESTADO=TEXTO] \
  [--clear-state-labels] \
  [--token NOMBRE=VALOR] \
  [--clear-token NOMBRE] \
  [--seq N] \
  [--ttl-ms N]

ESTADO es uno de idle, working, blocked, done o unknown. --agent y --applies-to-source protegen solo --title, --display-agent y --state-label. No protegen los parches de tokens; quien informa de los tokens se encarga de borrarlos o refrescar su TTL. Usa --display-agent para cambiar el nombre visible.

El texto de los metadatos se normaliza antes de guardarse. Herdr recorta los espacios de los extremos, elimina los caracteres de control y limita --title, --display-agent, cada --state-label y los valores de token a 80 caracteres. Un valor de token que quede vacío al normalizarlo borra esa clave.

--token modifica un valor visual con nombre; --clear-token elimina uno. Los tokens no mencionados no cambian. Los tokens de panel están disponibles en las filas de agente de la barra lateral como $name; los de espacio de trabajo, en las filas de espacio. El TTL se aplica de forma independiente a las claves de token actualizadas en esa llamada.

--source y --applies-to-source deben tener 80 caracteres o menos y solo pueden contener letras ASCII, dígitos, dos puntos, punto, guion bajo y guion. --ttl-ms hace que los metadatos caduquen solos y debe estar entre 1 y 86400000 milisegundos. Omítelo para metadatos que deban quedarse hasta que se sustituyan, se borren o se cierre el panel. --seq permite a Herdr ignorar los informes atrasados de la misma --source; la API los acepta, pero el estado del panel los ignora. Un panel o espacio de trabajo acepta informes de tokens con secuencia de como mucho 32 fuentes distintas durante su vida; borrar o caducar no libera esos huecos.

Agentes

Para el modelo de panel frente a agente y ejemplos completos de orquestación, mira Automatización con agentes.

herdr agent list
herdr agent get <destino>
herdr agent read <destino> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi]
herdr agent send-keys <destino> <tecla> [tecla ...]
herdr agent prompt <destino> <texto> [--wait] [--until ESTADO]... [--timeout MS]
herdr agent rename <destino> <nombre>|--clear
herdr agent focus <destino>
herdr agent wait <destino> [--until ESTADO]... [--timeout MS]
herdr agent attach <destino> [--takeover]
herdr agent start <nombre> --kind TIPO --pane ID [--timeout MS] [-- <argumentos-del-agente...>]
herdr agent explain <destino> [--json|--verbose]
herdr agent explain --file RUTA --agent ETIQUETA [--json|--verbose]

Los destinos de agente son un nombre único de agente vivo o el ID del panel que lo aloja en ese momento. Los IDs de terminal y las etiquetas genéricas de tipo de agente no son destinos válidos. Los agentes arrancados con agent start requieren un nombre; los lanzados a mano no tienen nombre y usan su ID de panel.

agent start activa un panel de shell existente y disponible: el shell interactivo del panel debe tener el primer plano, sin ningún comando, editor ni agente en marcha. La topología hay que crearla aparte. Los nombres son únicos entre los agentes vivos y deben cumplir [a-z][a-z0-9_-]{0,31}. El tipo selecciona el ejecutable interactivo canónico de Herdr, y los argumentos tras -- se pasan a ese ejecutable. Los tipos admitidos son pi, claude, codex, gemini, cursor, devin, agy, cline, omp, mastracode, opencode, copilot, kimi, kiro, droid, amp, grok, hermes, kilo, qodercli, qwen, letta, maki y muse. El nombre sigue al ocupante actual del panel y se borra cuando ese agente sale, se libera o se sustituye. Una incertidumbre temporal en la detección no lo borra.

Un arranque correcto devuelve solo cuando el agente esperado es dueño de esa terminal y está listo para recibir entrada interactiva. Si la detección informa de blocked durante el arranque, el comando devuelve agent_not_ready de inmediato. El nombre sigue disponible para agent read y agent send-keys, y queda listo para prompts cuando la detección informe de idle. El tiempo límite de arranque por defecto es de 30000 milisegundos; los valores explícitos deben ser mayores que 3000 y no superar 300000.

agent prompt respeta el modo de pegado entre corchetes activo y escribe el texto seguido de un Intro retardado como un único envío ordenado, también mientras el agente está trabajando. El éxito sin --wait confirma las escrituras, no el inicio de un turno. En Windows, Codex recibe un límite de pegado antes del Intro para que el envío no dependa del tamaño del prompt; el tiempo límite de quien llama incluye el tiempo de envío. Si el agente ya está blocked, devuelve agent_blocked sin enviar entrada. Con --wait, un prompt enviado desde otro estado que no sea trabajando tiene hasta cinco segundos tras el envío para producir un estado working o blocked observado, o Herdr devuelve agent_prompt_stalled; si el tiempo límite de quien llama expira antes, Herdr devuelve el error timeout normal. Así se evita que cambios de idle, done o de sesión no relacionados completen la espera. Una vez observada actividad, espera al primer estado estable pedido. No sigue turnos individuales. Si el agente ya estaba trabajando, la finalización de ese turno puede satisfacer la espera. --until acota los estados que valen y se rechaza si no va acompañado de --wait. Un agent wait suelto devuelve de inmediato cuando el estado actual coincide. Ambos usan por defecto idle, done o blocked; usa --until unknown de forma explícita cuando lo necesites.

idle y done significan los dos «listo para recibir entrada». La CLI y la API usan el estado de visto del servidor: done es en espera pero aún no marcado como visto, los comandos explícitos pane focus y agent focus marcan el destino como visto, y las lecturas no. Cada cliente de la interfaz lleva la cuenta de las finalizaciones vistas por separado, así que su marca Done puede diferir de la CLI o de otro cliente. blocked significa que Herdr ha reconocido una interfaz de aprobación o pregunta. unknown significa que hay un agente pero Herdr no puede clasificarlo con seguridad, no que su trabajo haya terminado bien.

agent send-keys envía teclas lógicas de terminal como enter, up, esc o ctrl+c. Herdr valida todas las teclas antes de escribir ningún byte. agent read lee el flujo resuelto de la terminal, y agent rename da nombre a un agente ya detectado.

agent explain pide al servidor en marcha que clasifique la misma instantánea de detección del fondo del búfer que usa la detección por pantalla, así que la salida en vivo refleja la caché de manifiestos activa del servidor. Como usa el método de socket agent.explain, tras actualizar Herdr reinicia el servidor o haz un traspaso a uno actualizado antes de usar el explain en vivo. Usa --file RUTA --agent ETIQUETA para explicar en local una captura guardada. La salida por defecto muestra el agente, el estado final, la fuente y versión del manifiesto, la regla que ha coincidido con su evidencia de regiones, y los motivos de respaldo, omisión o aviso. Añade --verbose para los indicadores de evidencia visible, la versión remota en caché, si un fichero local tapa otro, el estado de la actualización remota y la lista completa de reglas evaluadas con su evidencia. Añade --json para informes de errores o pruebas.

Usa pane send-text, pane send-keys, pane run y terminal attach para terminales normales, servidores, pruebas, shells o control de terminal a bajo nivel. Usa pane run cuando quieras enviar un comando con Intro.

Conexión directa a una terminal

herdr terminal attach <terminal_id> [--takeover]
herdr terminal session control <destino> [--takeover] [--cols N] [--rows N]
herdr terminal session observe <destino> [--cols N] [--rows N]
herdr terminal title set <título>
herdr terminal title clear

Desconecta de la conexión directa con ctrl+b q. Para enviar un ctrl+b literal, ctrl+b ctrl+b. terminal session control abre un flujo de terminal en vivo con escritura para un panel, una terminal o un agente. Imprime los mismos registros terminal.frame y terminal.closed, uno por línea, que el modo de observación. Lee por la entrada estándar comandos JSON, uno por línea: terminal.input, terminal.resize, terminal.scroll y terminal.release. Solo un controlador puede ser dueño de una terminal a la vez; usa --takeover para sustituirlo. terminal session observe abre un flujo de terminal en vivo de solo lectura para un panel, una terminal o un agente. Imprime registros JSON terminal.frame, uno por línea, con los bytes ANSI en base64, y después un registro terminal.closed cuando el servidor cierra el flujo. Varios observadores pueden mirar la misma terminal sin tomar la entrada, el tamaño, el desplazamiento ni la propiedad. En Linux y macOS, un observador se desconecta si una escritura en el socket no avanza durante 30 segundos. Un flujo atascado puede terminar sin un terminal.closed final; el panel y los demás clientes siguen funcionando. Los paneles en silencio no disparan ese tiempo límite. terminal title clear devuelve el título de la ventana de la terminal exterior a ui.window_title.

Esperas de salida

Espera a que aparezca una salida en un panel:

herdr pane wait-output <pane_id> (--match <texto> | --regex <patrón>) [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--raw]

Usa pane wait-output para comandos y servidores normales. Usa agent wait para agentes de programación.

pane wait-output comprueba de inmediato la instantánea seleccionada, incluida la salida que ya existe, y después sondea hasta que coincide. La fuente por defecto se llama recent; la comparación la trata como salida reciente desenvuelta de las últimas 80 filas de terminal pintadas. --lines cambia ese límite. --match busca una subcadena literal en una línea, y --regex usa la sintaxis de expresiones regulares de Rust y también compara línea a línea.

Un tiempo límite o un agent_prompt_stalled no demuestran que el prompt no se entregara. Inspecciona el agente antes de reintentar.

pane wait-output y agent wait esperan indefinidamente cuando se omite --timeout. En agent prompt --wait, la espera del estado estable es indefinida una vez observada actividad o cuando el prompt empieza en working; un prompt que no empieza trabajando sigue devolviendo agent_prompt_stalled tras cinco segundos sin actividad observada. Un tiempo límite o un error del servidor se emiten como JSON por la salida de error con código de salida 1. Los errores de uso de la CLI salen con código 2.

Integraciones

herdr integration install pi
herdr integration install omp
herdr integration install claude
herdr integration install codex
herdr integration install copilot
herdr integration install devin
herdr integration install droid
herdr integration install kimi
herdr integration install opencode
herdr integration install kilo
herdr integration install hermes
herdr integration install qodercli
herdr integration install qwen
herdr integration install letta
herdr integration install cursor
herdr integration install mastracode
herdr integration install grok
herdr integration uninstall pi
herdr integration uninstall omp
herdr integration uninstall claude
herdr integration uninstall codex
herdr integration uninstall copilot
herdr integration uninstall devin
herdr integration uninstall droid
herdr integration uninstall kimi
herdr integration uninstall opencode
herdr integration uninstall kilo
herdr integration uninstall hermes
herdr integration uninstall qodercli
herdr integration uninstall qwen
herdr integration uninstall letta
herdr integration uninstall cursor
herdr integration uninstall mastracode
herdr integration uninstall grok
herdr integration status [--outdated-only]

Plugins

Los comandos de plugin instalan y ejecutan plugins locales ejecutables de flujo de trabajo. Un plugin es un manifiesto más comandos fuera de proceso; Herdr es dueño de la superficie de acogida y los plugins de su lenguaje de implementación.

Instalar, listar y eliminar plugins:

herdr plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]
herdr plugin list [--plugin ID] [--json]
herdr plugin uninstall <plugin_id|owner/repo[/subdir...]>
herdr plugin enable <plugin_id>
herdr plugin disable <plugin_id>

plugin install solo acepta la forma abreviada de GitHub, como ogulcancelik/herdr-plugin-examples/worktree-bootstrap. Usa git, muestra una vista previa de confianza en terminales interactivas, ejecuta los comandos de construcción admitidos del manifiesto y guarda las instalaciones de GitHub en un directorio gestionado por Herdr. Usa --yes para instalaciones no interactivas. Reinstalar un plugin gestionado desde GitHub reemplaza esa copia gestionada. Instalar sobre un plugin enlazado localmente se rechaza. Los manifiestos deben declarar min_herdr_version; instalar y enlazar fallan cuando el plugin requiere un binario de Herdr más nuevo. plugin list es legible por defecto; pasa --json para la respuesta de la API en bruto.

La instalación y el estado de activación de los plugins son globales para el usuario actual. Un plugin instalado, enlazado, activado o desactivado desde una sesión de Herdr está disponible de inmediato, con el mismo estado, en todas las sesiones.

Desarrollo local:

herdr plugin link <ruta> [--disabled]
herdr plugin unlink <plugin_id>

plugin link acepta un directorio de plugin que contenga herdr-plugin.toml o la ruta directa a un manifiesto. Úsalo mientras escribes o pruebas un plugin desde una copia local. plugin unlink desregistra el plugin y no toca los ficheros. plugin uninstall desregistra un plugin y además elimina los ficheros de la copia de GitHub gestionada por Herdr. En las instalaciones de GitHub, la desinstalación acepta tanto el id del plugin como la misma forma abreviada owner/repo[/subdir...] que la instalación. Las acciones, los ganchos de eventos, los paneles y los manejadores de enlaces se declaran en el manifiesto; el registro de acciones en tiempo de ejecución no forma parte de la v1.

Directorio de configuración:

herdr plugin config-dir <plugin_id>

plugin config-dir imprime el directorio de configuración del plugin. Lo crea si hace falta y lo rellena a partir de las ubicaciones antiguas de configuración cuando existen. Úsalo en documentación de instalación y scripts de shell para dar a los usuarios una ruta estable para ficheros .env y otra configuración editable, separada de la copia gestionada del plugin.

Acciones:

herdr plugin action list [--plugin ID]
herdr plugin action invoke <action_id> [--plugin ID]

plugin action invoke arranca el comando del manifiesto de una acción de un plugin instalado, activado y compatible con la plataforma, e imprime en la respuesta JSON el registro del comando arrancado. Usa el id de acción cualificado (plugin.id.accion) cuando más de un plugin use el mismo id de acción. Los ids de acción locales no pueden contener puntos, así que los ids cualificados no son ambiguos aunque los ids de plugin contengan puntos.

Registros:

herdr plugin log list [--plugin ID] [--limit N]

Paneles de terminal gestionados:

herdr plugin pane open --plugin ID --entrypoint ID [--placement overlay|popup|split|tab|zoomed] [--width TAMAÑO] [--height TAMAÑO] [--workspace ID] [--target-pane PANEL] [--direction right|down] [--cwd RUTA] [--env CLAVE=VALOR] [--focus|--no-focus]
herdr plugin pane focus <pane_id>
herdr plugin pane close <pane_id>

plugin pane open requiere que el plugin esté enlazado, activado y sea compatible con la plataforma actual. Arranca un comando [[panes]] declarado en el manifiesto como panel de terminal gestionado por Herdr. El valor por defecto del manifiesto es overlay, que abre una superposición temporal ampliada sobre el panel activo. También puede abrirse como división, como pestaña nueva, como panel ampliado o como ventana emergente popup modal de sesión que no cambia la disposición de la pestaña. --width y --height fijan las dimensiones exteriores de la ventana emergente en celdas de terminal o en porcentajes como 80%; las dimensiones omitidas son la mitad del tamaño de la terminal, y los valores menores que el mínimo se ajustan. Una ventana emergente no es un panel de Herdr, no exporta HERDR_PANE_ID y no participa en las API de panel ni de agente. Los paneles de plugin nativos fuera de la terminal quedan fuera de la v1.

--env CLAVE=VALOR se puede repetir en los comandos que lanzan procesos. Se aplica solo al proceso recién lanzado. Las variables gestionadas por Herdr, como HERDR_SOCKET_PATH, HERDR_BIN_PATH, HERDR_ENV, HERDR_WORKSPACE_ID, HERDR_TAB_ID, HERDR_PANE_ID, HERDR_PLUGIN_ID, HERDR_PLUGIN_ROOT, HERDR_PLUGIN_CONFIG_DIR, HERDR_PLUGIN_STATE_DIR, HERDR_PLUGIN_ENTRYPOINT_ID y HERDR_PLUGIN_CONTEXT_JSON, prevalecen cuando entran en conflicto con las que aporta quien llama.

Fuentes de lectura

Fuente	Significado
visible	Pantalla pintada actual. La mejor para bucles de comprobación de la interfaz.
recent	Historial reciente con el ajuste de línea de la terminal.
recent-unwrapped	Historial reciente sin ajuste de línea. La mejor para registros.
detection	Instantánea del fondo del búfer que usa la detección de agentes por pantalla.

Estos significados se aplican a las lecturas. Solo en pane wait-output, tanto recent como recent-unwrapped buscan en la instantánea reciente desenvuelta; recent sigue siendo la forma por defecto.

Variables de entorno

Variable	Para qué sirve
HERDR_CONFIG_PATH	Cambia la ruta del fichero de configuración.
HERDR_SESSION	Selecciona una sesión con nombre para los comandos de la CLI.
HERDR_SOCKET_PATH	Cambia la ruta del socket, a bajo nivel.
HERDR_PROCESS_DETECTION	Estrategia de detección de procesos en Linux: native (por defecto) o child-groups (opcional).
HERDR_ENV	Vale 1 dentro de los procesos de panel gestionados por Herdr.
HERDR_PANE_ID	Id público del panel del proceso en marcha.
HERDR_TAB_ID	Id público de la pestaña del proceso en marcha.
HERDR_WORKSPACE_ID	Id público del espacio de trabajo del proceso en marcha.
HERDR_LOG	Filtro de registro, por ejemplo HERDR_LOG=herdr=debug.
HERDR_DISABLE_SOUND	Desactiva la reproducción de sonido aunque las notificaciones sonoras estén activas.