Design de CLI para agentes de IA: JSON, códigos de saída e espera

Uma CLI para agentes de IA não é apenas uma ferramenta de linha de comando para humanos que, por acaso, pode ser chamada por um modelo. Ela é um protocolo operacional. O agente precisa de entradas determinísticas, saídas estruturadas, códigos de saída significativos, categorias de erro estáveis e uma forma de esperar até que a infraestrutura assíncrona alcance um estado final.

Sem esse contrato, o agente é forçado a inferir o sucesso a partir de frases como “deploy iniciado”. Essa inferência é perigosa, porque uma solicitação aceita pode falhar posteriormente durante o build, as verificações de integridade, a inicialização do container ou a troca do tráfego.

Por que presumir que um deploy foi bem-sucedido é perigoso?

A maioria das operações de infraestrutura é assíncrona. Uma API pode aceitar um deploy e retornar um ID em milissegundos, enquanto o build real leva vários minutos. Se um agente relatar sucesso no momento em que a solicitação é aceita, todas as etapas seguintes serão baseadas em uma premissa falsa.

Considere a diferença:

Evento	O que ele comprova	O que ele não comprova
Solicitação aceita	A plataforma entendeu a solicitação	Que o código foi compilado
Build concluído	Uma imagem ou artefato foi criado	Que o app foi iniciado
Verificação de integridade aprovada	A nova instância respondeu conforme exigido	Que os fluxos de negócio funcionam
Tráfego alterado	O release se tornou ativo	Que ele continuará saudável
Observação de uptime	O serviço continua acessível	Que todos os recursos estão corretos

Um humano pode perceber essa diferença em um dashboard. Um agente operando por texto precisa que ela esteja codificada na interface.

O contrato de comandos do Dockup separa o enfileiramento da conclusão. Um deploy sem --wait retorna imediatamente com waited:false; um deploy com --wait bloqueia até obter sucesso, falha ou timeout:

dockup deploy production/api --wait --json

O timeout padrão é de 900 segundos. O comando termina com 0 somente depois de um estado terminal bem-sucedido. Ele termina com um valor diferente de zero e deploy_failed ou deploy_timeout quando o resultado não é sucesso.

O que uma CLI com JSON estruturado oferece a um agente de IA?

O JSON estruturado substitui a interpretação de prosa por campos nomeados. O agente pode localizar diretamente status, deploymentId, target ou code, sem depender de pontuação, cores, largura de colunas ou formulação textual.

Um resultado bem-sucedido pode ser consumido como dados:

{
  "ok": true,
  "target": "production/api",
  "deploymentId": "dep_123",
  "waited": true,
  "status": "success",
  "durationMs": 142381,
  "url": "https://api.dockup.tech"
}

Uma falha usa o mesmo formato de transporte:

{
  "ok": false,
  "error": "Deployment failed",
  "code": "deploy_failed"
}

A regra de design importante é que o JSON seja gravado em stdout, enquanto os avisos que não podem corromper o parsing sejam enviados para stderr. Os logs no modo follow usam NDJSON — um objeto JSON por linha — para que o chamador possa processar o fluxo incrementalmente sem esperar por um único array enorme.

O Dockup aplica --json a toda a sua superfície de comandos. Com 135 comandos, exigir que um agente deduza flags de memória seria frágil. A referência da CLI e a skill empacotada fornecem as instruções de comandos alinhadas à versão que o agente deve seguir.

A propriedade de design importante não é uma descoberta sofisticada. É garantir que o agente receba orientações operacionais atuais e estruturadas, sem inventar uma flag a partir de um prompt antigo.

Como códigos de saída reais controlam a automação de deploy?

O código de saída do sistema operacional é o sinal de sucesso mais portátil disponível para shell scripts, executores de CI e agentes de programação. A saída 0 significa que o comando alcançou o resultado definido. Um valor diferente de zero significa que o chamador deve seguir para recuperação, escalonamento ou encerramento.

Este trecho de shell é propositalmente simples:

if dockup deploy production/api --wait --json > result.json; then
  echo "deployment reached success"
else
  dockup logs production/api --build --json
  exit 1
fi

Ele não procura a palavra “success” no stdout. Também não presume que uma resposta HTTP 202 signifique que a produção está pronta. Em vez disso, delega a definição de sucesso à CLI e propaga a falha para o processo pai.

Códigos de saída reais são igualmente importantes para comandos executados uma única vez dentro de um container. O comando exec PRO do Dockup retorna stdout, stderr e o código de saída real do comando:

dockup exec "npm run migrate" \
  -s production/api \
  --json

Assim, um agente pode distinguir uma migração concluída de um comando que apenas foi iniciado. Esse é um princípio fundamental das barreiras de proteção para agentes de IA em produção.

Como a espera por estados terminais substitui o polling frágil?

Loops de polling escritos manualmente introduzem decisões de política ocultas: com que frequência fazer polling, quais estados são terminais, por quanto tempo esperar, se um erro de rede transitório deve reiniciar o cronômetro e o que fazer quando um container reinicia.

Um agente tem ainda mais chances de errar nessas decisões, porque pode não conhecer a máquina de estados completa da plataforma. A plataforma deve ser responsável pela semântica de espera.

O Dockup oferece dois padrões úteis:

dockup deploy production/api --wait --timeout 1800 --json
dockup push --json

deploy --wait espera explicitamente. push espera por padrão depois de fazer o push e disparar o release; --no-wait desativa esse comportamento. Ambos retornam um código de saída que reflete o resultado terminal.

O acompanhamento de logs segue a mesma ideia:

dockup logs production/api --build -f --json

O fluxo termina quando o build chega a um estado de sucesso ou falha. Um objeto NDJSON final indica done:true, e um build com falha termina com um valor diferente de zero. O chamador não precisa de uma segunda implementação de polling.

Para verificar a disponibilidade da aplicação após o deploy, o comando de uptime do Dockup retorna verificações em nível de minuto, tempo médio de resposta e p95:

dockup uptime production/api --hours 24 --json

Espera e monitoramento são conceitos separados. --wait responde se este deploy alcançou um resultado terminal; uptime responde como o serviço em execução se comportou ao longo do tempo.

Quais códigos de erro um agente deve conhecer?

Categorias de erro estáveis permitem que um agente execute uma ação limitada sem interpretar cada mensagem possível. O Dockup expõe códigos como:

Código de erro	Significado	Resposta segura do agente
not_logged_in	Nenhum token utilizável	Parar e solicitar autenticação
not_linked	Nenhum destino .dockup para push	Resolver ou informar o destino
no_target	Não foi possível identificar o serviço	Executar services --json
needs_confirm	A ação destrutiva não tem aprovação	Solicitar confirmação humana
deploy_trigger_failed	Não foi possível iniciar o deploy	Relatar o erro da API
deploy_failed	O build ou deploy terminou com falha	Ler os logs do build
deploy_timeout	Ainda em execução após o limite de espera	Relatar a incerteza ou estender deliberadamente

A mensagem de erro continua sendo um contexto útil, mas é o código que orienta a primeira decisão. Isso torna a automação resistente a alterações na redação ou na localização.

A confirmação também faz parte do protocolo. Um comando destrutivo não deve prosseguir silenciosamente porque o chamador não é interativo. O Dockup recusa essas operações sem --yes e retorna needs_confirm. Um agente autônomo vê uma pergunta, não uma barreira a ser contornada.

O modelo de segurança é explorado em mais detalhes nas boas práticas de segurança.

Qual é o contrato mínimo para uma CLI pronta para produção?

Uma CLI para agentes de IA pronta para produção deve cumprir um contrato pequeno, porém rigoroso:

1. Toda operação de leitura e escrita tem saída legível por máquina.
2. Uma falha produz um valor diferente de zero no processo.
3. Mutações assíncronas podem esperar por um estado terminal documentado.
4. Valores secretos nunca são retornados por comandos de leitura.
5. Ações destrutivas exigem confirmação explícita.
6. Os erros têm códigos estáveis adequados para decisões condicionais.
7. O pacote da CLI e as instruções do agente permanecem alinhados à versão.
8. As mutações são registradas em uma trilha de auditoria.

A skill do Dockup transforma essas regras em comportamento padrão para Claude Code e Codex. Ela orienta o agente a usar JSON, autenticar com DOCKUP_TOKEN, descobrir destinos exatos, fazer deploy com --wait, proteger credenciais e parar diante de needs_confirm.

Compare esse modelo com os conceitos mais amplos em skills de agentes vs MCP. Uma skill fornece conhecimento operacional; a CLI continua sendo a interface executável cujo status de saída e saída definem a realidade.

Uma matriz de testes para um comando voltado a agentes

Antes de disponibilizar qualquer comando de infraestrutura para um agente, teste mais do que o caminho feliz:

Teste	Comportamento esperado
Solicitação válida	Resultado JSON e saída 0
Token inválido	Código de autenticação estável e saída diferente de zero
Destino desconhecido	Código de destino estável e nenhuma mutação
Deploy de longa duração	Espera até o estado terminal ou timeout
Deploy com falha	Saída diferente de zero e ID do deploy para diagnóstico
Aprovação destrutiva ausente	needs_confirm, sem exclusão
Leitura de segredo	Metadados da chave visíveis, valor mascarado
Aviso durante a saída JSON	Aviso em stderr, JSON válido em stdout

Essa matriz é mais valiosa do que um spinner de progresso sofisticado. A formatação para humanos pode ser adicionada por cima; um contrato determinístico para máquinas não pode ser reconstruído depois.

A documentação da CLI do Dockup mostra os comandos concretos por trás desse modelo, enquanto o artigo sobre desenvolvimento com IA explica a mudança mais ampla do uso manual de ferramentas para fluxos de trabalho orientados por agentes.

Trate a observabilidade como parte do contrato do comando

Uma mutação voltada para agentes deve retornar identificadores que possibilitem investigações posteriores. Uma resposta de deploy precisa do destino e do ID do deploy; um banco de dados criado precisa de um slug estável; um snapshot de volume precisa do ID do snapshot. Sem essas referências, o agente pode descrever um evento, mas não consegue inspecionar, repetir ou reverter a operação com confiabilidade.

A trilha de auditoria completa o contrato. A saída estruturada explica uma invocação, enquanto os registros de auditoria conectam várias invocações ao longo do tempo. Juntos, eles permitem que os operadores respondam se o agente atuou sobre o recurso pretendido e se um comando posterior de recuperação se referiu ao mesmo evento de produção.

Mantenha a interface simples

Uma CLI para agentes de IA confiável deve ser previsível em situações de sucesso, falha, timeout e nova tentativa.

Teste final da interface

A CLI para agentes de IA deve falhar de forma verdadeira.

Coloque o fluxo de trabalho em produção

Teste o contrato primeiro a partir de um shell: verifique o parsing de JSON, uma saída bem-sucedida, uma falha forçada, um timeout e uma operação destrutiva bloqueada antes de delegar o acesso à produção.

npm install -g dockup-cli
dockup skill install

O primeiro comando instala a CLI. O segundo instala a skill correspondente do Dockup para Claude Code e Codex. Comece gratuitamente em app.dockup.ai.

FAQ

O que torna uma CLI adequada para agentes de IA?

Ela precisa de saída estruturada, códigos de saída reais, espera por estados terminais, códigos de erro estáveis, mascaramento de segredos e confirmação explícita para operações destrutivas.

Por que o JSON é melhor do que a saída de CLI formatada para humanos para agentes?

O JSON fornece nomes e tipos de campos estáveis. O agente não precisa inferir significado a partir de cores, tabelas, pontuação ou textos que mudam.

Por que uma solicitação de deploy aceita não representa sucesso?

A aceitação apenas comprova que a plataforma enfileirou a operação. O build, a inicialização, a verificação de integridade e a troca de tráfego posteriores ainda podem falhar.

Qual é o timeout padrão de espera do deploy no Dockup?

O timeout padrão de dockup deploy --wait é de 900 segundos e pode ser alterado com a opção documentada --timeout.

Como um agente deve reagir a needs_confirm?

Ele deve parar e solicitar aprovação explícita. O código significa que a ação solicitada é destrutiva e não foi executada intencionalmente.