Sortie JSON et automatisation

Le CLI est conçu pour être lu par des scripts et des agents. JSON est la sortie par défaut ; les tableaux et le JSON délimité par lignes s’activent sur demande.

L’enveloppe

Chaque commande réussie imprime un objet JSON sur stdout :

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

changed indique si la commande a réellement modifié quelque chose — false signifie que l’état souhaité existait déjà. data contient le résultat : des listes de canaux ou de messages, un message avec son contenu en JSON réellement imbriqué, des confirmations de commande.

Les erreurs partent sur stderr en JSON et ne touchent jamais stdout :

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

Codes de sortie

Code	Signification
0	Succès, y compris un no-op (`changed: false`)
1	Erreur interne
2	Erreur d’utilisation ou de configuration
3	Authentification requise ou échouée
4	Permission refusée ou précondition non remplie
5	Introuvable ou conflit
6	Délai dépassé, indisponible ou limite de débit atteinte

Un modèle de script robuste :

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

Formats de sortie

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

Options globales utiles

--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

La variable d’environnement HANSA_CONFIG déplace l’ensemble du fichier de contexte, ce qui permet à des tâches parallèles d’utiliser des contextes isolés. L’alimentation en jetons headless et le comportement du trousseau sont décrits dans Authentification et espaces de travail.

Notes de sécurité

Les identifiants ne résident que dans le trousseau du système d’exploitation ou l’environnement du processus — jamais dans la sortie, les journaux ni le fichier de contexte.
Les diagnostics --verbose filtrent les en-têtes d’autorisation, la saisie des identifiants et les réponses de renouvellement.
Tous les identifiants sont émis sous forme de chaînes JSON, les horodatages en UTC RFC3339 ; le contenu des messages apparaît en JSON réellement imbriqué, et non en chaîne entre guillemets.