skill oficial/cli
Você é uma IA controlando um servidor glyph através de sua CLI. Esta skill é um mapa de toda a superfície de comandos glyph além das convenções que não são óbvias a partir de --help — mais importante, a disciplina de escopo de workspace que impede que seus comandos entrem em conflito com outros clientes, e a disciplina de código de saída / código de erro que permite ramificar mecanicamente com base em falhas.
Configuração
glyph injeta o que você precisa em seu ambiente quando inicia sua tarefa ou sessão:
GLYPH_SERVER— URL do servidor (a CLI usa automaticamente)GLYPH_WORKSPACE— UUID do workspace (comandos com escopo de workspace o herdam)
Verificação rápida:
glyph health # saída 0 ⇒ CLI funciona + servidor acessível
glyph workspace current --json | jq # confirma workspace resolvido
Superfície de comandos de relance
Todo comando com escopo de workspace herda --server / --workspace-id / --output / --json e segue a tabela de código de saída compartilhada abaixo. Os grupos de subcomandos:
| Grupo | Propósito | Referência |
|---|---|---|
workspace | Criar / listar / exibir / atualizar / remover / recarregar workspaces; imprimir id atual | references/commands.md#workspace |
session | Gerenciar sessões interativas (listar / nova / exibir / remover / iniciar um terminal) | references/commands.md#session |
task | Despachar tarefas únicas, listar (incluindo escopo por --origin), inspecioná-las, acompanhar atividade, cancelar, remover | references/commands.md#task |
schedule | Lançadores de tarefas acionados por cron (criar / listar / patch / habilitar / desabilitar / executar / visualizar / listar-tarefas) | references/commands.md#schedule |
catalog | Instalar / sincronizar / habilitar / desabilitar agentes, skills, MCPs | references/commands.md#catalog |
workflow | Semear um workflow, ler/mutar seu DAG ativo (expandir, aplicar patch na especificação de um nó not_started via update-spec), responder a nós humanos, encerrar | references/commands.md#workflow |
runtime | Listar runtimes registrados (copilot, etc) | references/commands.md#runtime |
| Inspeção do servidor | health, config, status, logs — sem ciclo de vida | references/commands.md#server-inspection |
| Ciclo de vida do servidor | serve / start / stop / restart — fora do escopo desta skill | — |
Disciplina de workspace
Todo comando com escopo de workspace requer um seletor explícito. A CLI lê GLYPH_WORKSPACE do seu ambiente (já definido), então os comandos funcionam como estão:
glyph task dispatch --agent writer --brief "..."
Para atuar em um workspace diferente, passe --workspace-id <id> por comando:
glyph task list --workspace-id ws-Y
A CLI não consulta nenhum estado compartilhado de "workspace atual" no lado do servidor — os seletores são locais ao processo, imunes a interferências de outros clientes (outras sessões CLI, abas do dashboard, agentes de IA no mesmo servidor).
Disciplina de saída
- Para análise, sempre passe
--json. O formato humano/tabela não é um contrato estável — a ordem das colunas e cabeçalhos mudam entre versões. - Para atividade em streaming, use pipe com
jq -cpara manter um evento por linha. - Cada formato
--jsonque você provavelmente consumirá está documentado emreferences/json-shapes.md. Consulte-o antes de escrever um filtrojq— a maioria dos formatos tem campos opcionais (presentes quando a linha subjacente não é nula) dos quais você deve depender.
Disciplina de erros
Erros em stderr sempre carregam um code:
agent "writer" não está pronto: pré-requisitos não reconhecidos (HTTP 409, EntryNotReadyError)
agent: acme/writer
cause: pré-requisitos não reconhecidos
fix: glyph catalog agent ack-prereqs acme/writer
A linha fix: é seu próximo comando, exatamente como está. O catálogo completo de code (todos os nomes de erro + HTTP típico + remediação) está em references/error-codes.md. Em particular:
EntryNotReadyErroré o ramo mais comum que você encontrará — ele carrega umreasonestruturado descrevendo se o agente precisa deack-prereqs, estádisabled, temmissingDeps, ou temblockedDeps(que recursam). A tabela de razões está emreferences/error-codes.md#entrynotreadyerror-reasons.
Códigos de saída
| código | significado | o que fazer |
|---|---|---|
| 0 | sucesso | continue |
| 1 | erro genérico (incl. workspace ausente) | leia stderr; geralmente flag/ambiente ausente |
| 2 | erro de uso (flag obrigatória ausente, subcomando removido) | corrija a invocação; não repita como está |
| 3 | servidor inacessível | peça ao usuário para glyph start ou verifique --server |
| 4 | servidor retornou 4xx/5xx | leia code em stderr; consulte references/error-codes.md |
Código de saída 2 significa "o comando em si está errado" — nunca repita sem alterar a invocação. Código de saída 4 significa "o servidor rejeitou isso" — leia o campo code, ele informa o próximo passo.
Armadilhas
- Para aguardar uma tarefa, use
glyph task activity <tid> --follow(SSE em tempo real). Polling detask listem um loop de shell desperdiça ciclos e atrasa eventos reais. - Para um instantâneo único "o que aconteceu até agora?", remova
--follow—glyph task activity <tid> --jsonretorna a atividade atual maistotalItemsem uma chamada.--followbloqueia até a tarefa terminar. - Encerre antes de remover.
task rm <tid>simples requer que a tarefa esteja em um estado terminal (succeeded/failed/cancelled); se ainda estiver em execução, useglyph task cancel <tid>primeiro, depoistask rm. Recorra a--purgeapenas quando também quiser que o diretório de trabalho + estado de runtime desapareçam (ostderr.logpós-mortem é perdido). A mesma distinção se aplica asession rmeworkspace rm. - Sempre retome
--followcom olast seq:impresso. Em cada saída limpa (event: endou fluxo fechado) E em saída por erro no meio do fluxo, a CLI imprimelast seq: <N>em stderr — passe--after <N>na próxima invocação de--followpara retomar sem lacunas ou duplicatas. Ctrl+C é a exceção (stderr não é liberado); derive o seq do último item NDJSON em stdout (... | tail -1 | jq .seq). O manual completo de retomada está emreferences/playbooks.md#monitor-a-long-running-task. - Sempre obtenha ids de workspace de
glyph workspace list --json | jq. Fragmentos de URL do dashboard variam entre versões e não são um contrato de interface. schedule patché esparso — apenas as flags que você passar vão para a rede. Para remover um campo, passe--clear-details/--clear-runtime(um--details ""vazio é tratado como omitido, não como limpeza).
Referências (leitura obrigatória antes de trabalho não trivial)
references/commands.md— referência de subcomandos por grupo (workspace / session / task / schedule / catalog / workflow / runtime / server inspection). Leia superficialmente uma vez, mantenha como consulta.references/playbooks.md— playbooks orientados a metas de várias etapas (instalar e verificar agente, despachar e aguardar, monitorar tarefa, sincronizar entrada, limpar, integrar novo workspace, criar um agente local rapidamente).references/json-shapes.md— os formatos comuns de payload--jsoncom listas de campos concretas e notas de opcionalidade.references/error-codes.md— todo valorcodeque o servidor emite + o comandoglyphcorrespondente para corrigi-lo.