HansaChat

Documentation

Saída JSON e automatização

Envelope de saída, códigos de saída, formatos e padrões seguros para scripts.

A CLI foi concebida para ser lida por scripts e agentes. O JSON é a saída predefinida; as tabelas e o JSON delimitado por linhas são opcionais.

O envelope

Cada comando bem-sucedido imprime um objeto JSON no stdout:

{
  "ok": true,
  "schema_version": "1",
  "workspace": "yourworkspace",
  "domain": "yourworkspace.hansa.chat",
  "changed": false,
  "data": { }
}

changed indica se o comando realmente alterou algo — false significa que o estado pretendido já existia. data contém o resultado: listas de canais ou mensagens, uma mensagem com o seu conteúdo como JSON aninhado real, confirmações de comandos.

Os erros vão para o stderr como JSON e nunca tocam no stdout:

{
  "ok": false,
  "schema_version": "1",
  "error": { "code": "unauthenticated", "message": "…", "retryable": false }
}

Códigos de saída

Código Significado
0 Sucesso, incluindo um no-op (changed: false)
1 Erro interno
2 Erro de utilização ou de configuração
3 Autenticação necessária ou falhada
4 Permissão recusada ou pré-condição falhada
5 Não encontrado ou conflito
6 Tempo limite esgotado, indisponível ou limite de pedidos atingido

Um padrão robusto para scripts:

if hansa chat channels ensure --name Deploy --type public >/dev/null 2>&1; then
  echo "channel ready"
fi

Formatos de saída

hansa chat channels list -o json    # default, one envelope
hansa chat channels list -o jsonl   # one JSON object per line
hansa chat channels list -o table   # aligned text columns for humans

Flags globais úteis

--workspace <alias-or-domain>   # override the workspace for one command
--timeout 30s                   # network timeout
--config /path/config.json      # custom context file (default: OS config dir)
--verbose                       # diagnostics to stderr, secrets filtered

A variável de ambiente HANSA_CONFIG muda o ficheiro de contexto de sítio, o que permite que tarefas paralelas usem contextos isolados. O fornecimento de tokens headless e o comportamento do keychain estão descritos em autenticação.

Notas de segurança

  • As credenciais vivem apenas no keychain do sistema operativo ou no ambiente do processo — nunca na saída, nos registos ou no ficheiro de contexto.
  • Os diagnósticos de --verbose filtram cabeçalhos de autorização, a entrada de credenciais e as respostas de renovação.
  • Todos os identificadores são emitidos como strings JSON e os carimbos de data/hora como UTC RFC3339; o conteúdo das mensagens aparece como JSON aninhado real, não como uma string entre aspas.