@sinoia/pulse-cli

pulse-cli

CLI pour l'API REST Pulse, pensé pour le pilotage par agent/LLM : sortie --json structurée, auth par clé API (pk_…) ou login JWT. Objectif n°1 : permettre à un agent de prendre des tickets support et d'y répondre.

Vit dans le repo Pulse, sous tools/cli/.

Installation

npm (global — nécessite Node ≥ 20)

npm install -g @sinoia/pulse-cli
pulse --version

Binaire autonome (sans Node)

Des exécutables autonomes (runtime Node embarqué) sont produits par pkg :

cd tools/cli
npm install
npm run package           # → binaries/pulse-cli-{macos-arm64,macos-x64,linux-x64,linux-arm64}
# ciblé : npm run package:macos | npm run package:linux

# installer (ex. macOS arm64)
sudo install binaries/pulse-cli-macos-arm64 /usr/local/bin/pulse
pulse --version

Aucune dépendance Node requise pour exécuter le binaire (~46 Mo, runtime inclus). Pour un agent : déposer le binaire de la plateforme et définir PULSE_TOKEN.

Depuis les sources (Node ≥ 20)

cd tools/cli
npm install
npm run build      # → dist/cli.js (bin: pulse)

En dev : npm run dev -- <commande> (ts-node).

Authentification

Deux modes :

# Humain : login email / mot de passe → JWT (stocké dans ~/.pulse-config.json, 0600)
pulse login -e moi@sinoia.fr -p '••••••'

# Agent autonome : clé API non-expirante (recommandé)
export PULSE_TOKEN=pk_xxxxxxxx          # générée via /profile + l'API api_keys
# ou : pulse config set-token pk_xxxxxxxx

Surcharges d'environnement : PULSE_API_URL (défaut https://pulse.sinoia.fr), PULSE_TOKEN. La clé/JWT voyage en Authorization: Bearer ….

L'auteur des réponses = l'utilisateur de la clé API (doit avoir un rôle support/agent). --as-support masque son nom côté client (« L'équipe support SINOIA »).

Commandes (toutes acceptent --json)

pulse whoami
pulse tickets ls [--status open] [--severity S1] [--queue <id>] [--mine] [--search "connexion"] [--page N]
pulse tickets show <id>
pulse tickets take <id>
pulse tickets assign <id> --agent <agentId>      # dispatch vers un agent (cf. pulse agents)
pulse tickets transfer <id> --queue <queueId>    # transfert vers une file (cf. pulse queues)
pulse tickets severity <id> S1                   # sévérité S1 (critique) → S4 (gênant) ; liste triée S1 d'abord
pulse tickets attachments <ticketId>             # liste les pièces jointes (id, nom, type, taille)
pulse tickets attachment <ticketId> <attId> [-o f] # télécharge le contenu d'une pièce jointe
pulse tickets reply <id> -m "Bonjour, …" [--internal] [--as-support] [--attach capture.png …]
pulse tickets suggest <id>                       # brouillon de réponse ancré sur la KB (relecture humaine)
pulse tickets close <id> [--reason "résolu"]
pulse tickets stats [--queue <id>]               # compteurs par statut
pulse agents                                     # agents (cibles d'assignation)
pulse queues                                     # files (cibles de transfert)

# Base de connaissances (enrichissement + lecture)
pulse kb ls [--search "bannette"] [--status published]
pulse kb show <id>
pulse kb add-from-ticket <ticketId> --title "…" --content "…" [--publish] [--tags a,b]

# Licences & vouchers (Phase 2 — nécessite un token ADMIN : pulse login d'un
# admin, ou une clé API pk_ d'un utilisateur admin)
pulse licenses ls [--status active] [--type pro] [--org <id>] [--expiration expiring_soon] [--limit N]
pulse licenses show <id>
pulse licenses suspend <id> [--reason "…"] | activate <id>
pulse licenses generate-voucher <id> [--max-uses N] [--instance <id>]
pulse licenses stats
pulse vouchers ls [--status …] [--license <id>] [--instance <id>]
pulse vouchers show <id>
pulse vouchers revoke <id> [--reason "…"]
pulse vouchers extend <id> --hours N

# Commandes du store (Phase 2 — token ADMIN)
pulse orders ls [--status failed] [--limit N]
pulse orders show <id>
pulse orders retry <id>          # rejoue le provisioning en échec (idempotent)
pulse orders cancel <id> [--reason "…"]

# Parc d'instances (Phase 2 — token ADMIN)
pulse instances ls [--status running] [--org <id>] [--limit N]
pulse instances show <id>
pulse instances credentials <id>   # identifiants admin (via la commande liée)

# CRM — leads & contacts (Phase 2 — rôles admin/commerce/commercial)
pulse leads ls [--status qualified] [--search "Acme"] [--org <id>] [--limit N]
pulse leads show <id>
pulse contacts ls [--search "curie"] [--org <id>] [--limit N]
pulse contacts show <id>

Usage agent (non interactif)

export PULSE_TOKEN=pk_…
pulse --json tickets ls --status open                 # triage
pulse --json tickets take <id>                        # prendre le ticket
pulse --json tickets suggest <id>                     # brouillon sourcé KB (relecture humaine, aucun envoi)
pulse --json tickets reply <id> -m "…" --attach shot.png --as-support

En mode --json, objets/listes sortent sur stdout ; les erreurs en JSON sur stderr ({ "ok": false, "error": … }), code de sortie 1.

Contrat d'API

OpenAPI servi par Pulse sur GET /api/v1/docs/openapi.json. Vendoré localement via npm run update:spec (→ openapi/pulse-api.json).

Architecture

src/
├── cli.ts      # entrée Commander, --json global, wiring des commandes
├── config.ts   # ~/.pulse-config.json (+ surcharges env)
├── api.ts      # client axios (Bearer clé API / JWT)
├── auth.ts     # login email/mot de passe → JWT
├── output.ts   # bascule JSON / tables humaines
└── query.ts    # mapping options de liste → params API