Habilidad oficial/cli
Eres una IA que controla un servidor glyph a través de su CLI. Esta habilidad es un mapa de toda la superficie de comandos glyph más las convenciones que no son obvias en --help — especialmente la disciplina de ámbito de espacio de trabajo que evita que tus comandos compitan con otros clientes, y la disciplina de código de salida / código de error que te permite ramificar mecánicamente en fallos.
Configuración
glyph inyecta lo que necesitas en tu entorno cuando inicia tu tarea o sesión:
GLYPH_SERVER— URL del servidor (la CLI lo usa automáticamente)GLYPH_WORKSPACE— UUID del espacio de trabajo (los comandos con ámbito de espacio de trabajo lo heredan)
Verificación rápida:
glyph health # código de salida 0 ⇒ CLI funciona + servidor accesible
glyph workspace current --json | jq # confirma que el espacio de trabajo está resuelto
Superficie de comandos de un vistazo
Cada comando con ámbito de espacio de trabajo hereda --server / --workspace-id / --output / --json y sigue la tabla de códigos de salida compartida a continuación. Los grupos de subcomandos:
| Grupo | Propósito | Referencia |
|---|---|---|
workspace | Crear / listar / mostrar / actualizar / eliminar / recargar espacios de trabajo; imprimir el id actual | references/commands.md#workspace |
session | Gestionar sesiones interactivas (listar / nueva / mostrar / eliminar / iniciar un terminal) | references/commands.md#session |
task | Despachar tareas únicas, listar (incl. filtrado por --origin), inspeccionarlas, seguir su actividad, cancelar, eliminar | references/commands.md#task |
schedule | Lanzadores de tareas activados por cron (crear / listar / parchear / habilitar / deshabilitar / ejecutar / previsualizar / listar-tareas) | references/commands.md#schedule |
catalog | Instalar / sincronizar / habilitar / deshabilitar agentes, habilidades, MCPs | references/commands.md#catalog |
workflow | Sembrar un flujo de trabajo, leer/mutar su DAG en vivo (expandir, parchear la especificación de un nodo not_started mediante update-spec), responder a nodos humanos, terminar | references/commands.md#workflow |
runtime | Listar tiempos de ejecución registrados (copilot, etc.) | references/commands.md#runtime |
| Inspección del servidor | health, config, status, logs — sin ciclo de vida | references/commands.md#server-inspection |
| Ciclo de vida del servidor | serve / start / stop / restart — fuera del alcance de esta habilidad | — |
Disciplina del espacio de trabajo
Cada comando con ámbito de espacio de trabajo requiere un selector explícito. La CLI lee GLYPH_WORKSPACE de tu entorno (ya configurado), por lo que los comandos funcionan tal cual:
glyph task dispatch --agent writer --brief "..."
Para actuar en un espacio de trabajo diferente, pasa --workspace-id <id> por comando:
glyph task list --workspace-id ws-Y
La CLI no consulta ningún estado compartido de "espacio de trabajo actual" del lado del servidor — los selectores son locales al proceso, inmunes a interferencias de otros clientes (otras sesiones CLI, pestañas del panel, agentes de IA en el mismo servidor).
Disciplina de salida
- Para análisis, usa siempre
--json. El formato humano/tabla no es un contrato estable — el orden de las columnas y los encabezados cambian entre versiones. - Para actividad en streaming, canaliza a través de
jq -cpara mantener un evento por línea. - Cada forma
--jsonque probablemente consumirás está documentada enreferences/json-shapes.md. Consúltalo antes de escribir un filtrojq— la mayoría de las formas tienen campos opcionales (presentes cuando la fila subyacente no es nula) que deberías usar como clave.
Disciplina de errores
Los errores en stderr siempre llevan un code:
agent "writer" is not ready: prereqs not acknowledged (HTTP 409, EntryNotReadyError)
agent: acme/writer
cause: prereqs not acknowledged
fix: glyph catalog agent ack-prereqs acme/writer
La línea fix: es tu siguiente comando, textual. El catálogo completo de code (todos los nombres de error + HTTP típico + remediación) está en references/error-codes.md. En particular:
EntryNotReadyErrores la rama más común que tomarás — lleva unreasonestructurado que describe si el agente necesitaack-prereqs, estádisabled, tienemissingDepso tieneblockedDeps(que se recorren recursivamente). La tabla de razones está enreferences/error-codes.md#entrynotreadyerror-reasons.
Códigos de salida
| código | significado | qué hacer |
|---|---|---|
| 0 | éxito | continuar |
| 1 | error genérico (incl. espacio de trabajo faltante) | leer stderr; normalmente falta un flag/env |
| 2 | error de uso (falta un flag obligatorio, subcomando eliminado) | corregir la invocación; no reintentar tal cual |
| 3 | servidor inalcanzable | pedir al usuario que glyph start o verifique --server |
| 4 | servidor devolvió 4xx/5xx | leer code en stderr; consultar references/error-codes.md |
El código de salida 2 significa "el comando en sí está mal" — nunca lo reintentes sin cambiar la invocación. El código de salida 4 significa "el servidor rechazó esto" — lee el campo code, te indica el siguiente paso.
Errores comunes
- Para esperar una tarea, usa
glyph task activity <tid> --follow(SSE en tiempo real). Sondeandotask listen un bucle de shell desperdicia ciclos y retrasa eventos reales. - Para una instantánea única de "¿qué ha pasado hasta ahora?", omite
--follow—glyph task activity <tid> --jsondevuelve la actividad actual mástotalItemsen una sola llamada.--followbloquea hasta que la tarea termina. - Termina antes de eliminar. Un simple
task rm <tid>requiere que la tarea esté en un estado terminal (succeeded/failed/cancelled); si aún se está ejecutando, primeroglyph task cancel <tid>, luegotask rm. Recurre a--purgesolo cuando también quieras que desaparezcan el directorio de trabajo + el estado del tiempo de ejecución (elstderr.logpost-mortem se pierde). La misma distinción aplica parasession rmyworkspace rm. - Siempre reanuda
--followcon ellast seq:impreso. En cada salida limpia (event: endo flujo cerrado) Y en salida por error en medio del flujo, la CLI imprimelast seq: <N>en stderr — pasa--after <N>en la siguiente invocación de--followpara reanudar sin huecos ni duplicados. Ctrl+C es la excepción (stderr no se vacía); deriva el seq del último elemento NDJSON de stdout (... | tail -1 | jq .seq). El manual completo de reanudación está enreferences/playbooks.md#monitor-a-long-running-task. - Siempre obtén los ids de espacios de trabajo de
glyph workspace list --json | jq. Los fragmentos de URL del panel varían entre versiones y no son un contrato de red. schedule patches disperso — solo los flags que pasas van al cable. Para eliminar un campo, pasa--clear-details/--clear-runtime(un--details ""vacío se trata como omitido, no como borrado).
Referencias (lectura obligatoria antes de trabajo no trivial)
references/commands.md— referencia de subcomandos por grupo (workspace / session / task / schedule / catalog / workflow / runtime / server inspection). Examínalo una vez, mantenlo como referencia.references/playbooks.md— manuales multi-paso orientados a objetivos (instalar-y-verificar agente, despachar-y-esperar, monitorear tarea, sincronizar entrada, limpiar, incorporar nuevo espacio de trabajo, crear un agente local sobre la marcha).references/json-shapes.md— las formas comunes de carga útil--jsoncon listas de campos concretas y notas de opcionalidad.references/error-codes.md— cada valor decodeque emite el servidor + el comandoglyphcorrespondiente para solucionarlo.