Documentation

Référence de la CLI ambih

La CLI ambih pilote l'application de surveillance depuis n'importe quel terminal — lancer des projets, interroger des sessions, comparer des exécutions et verrouiller la CI. Installez-la depuis Paramètres → CLI dans l'application.

Dernière mise à jour : 2026-06-02

Utilisation

La CLI communique avec l'application via un canal nommé propre à l'utilisateur (un socket de domaine Unix sous Linux/macOS). Si l'application n'est pas lancée, ambih start la démarre en mode barre des tâches et attend l'apparition du canal. Chaque commande accepte --json pour passer d'une sortie lisible à du JSON ligne par ligne, pour les agents et la CI.

ambih 
$ambih <commande> [options]

ambih start

Lance le projet ancré au répertoire courant et renvoie sa sortie dans votre terminal. La commande de lancement peut être passée en position (ambih start "npm run dev") ou via --cmd. Si un projet est déjà enregistré pour ce répertoire, la commande sauvegardée est utilisée ; en passer une nouvelle la met à jour. Sinon, un projet est auto-enregistré avec le nom du dossier (modifiable via --name). Ctrl+C arrête le projet — le terminal qui l'a lancé possède son cycle de vie. Si le projet est déjà en cours, la CLI propose de suivre la sortie existante ; forcez le choix avec --attach ou --no-attach.

Synopsis

ambih start 
ambih start ["COMMANDE"] [--name NOM] [--attach | --no-attach] [--json]

Options

--name NOM Nom à utiliser lors de l'auto-enregistrement d'un nouveau projet.
--cmd "…" Commande de lancement, à la place de la position.
--attach Toujours suivre un projet déjà en cours, sans demander.
--no-attach Ne jamais suivre ; quitter avec 0 sans toucher la session.
--json Diffuse session_started → log_line* → session_exited en NDJSON.

Exemple

bash 
$ambih start "npm run dev" --name web-app

ambih list

Affiche tous les projets enregistrés. Les projets en cours sont signalés.

Synopsis

ambih list 
ambih list | ls [--json]

Options

--json Émet un objet JSON par projet (is_running, name, id, …).

Exemple

bash 
$ambih list --json | jq -r 'select(.is_running) | .name'

ambih status

État en direct + dernière session d'un projet. En cours : id de session, durée, branche git et le dernier échantillon de ressources à 1 Hz (CPU / mémoire / disque / réseau). À l'arrêt : la session persistée la plus récente avec son issue, sa durée, son code de sortie et ses stats agrégées.

Synopsis

ambih status 
ambih status <projet> [--json]

Options

--json Émet l'état sous forme d'un unique objet JSON.

Exemple

bash 
$ambih status web-app

ambih history

Sessions récentes d'un projet, de la plus récente à la plus ancienne. Chaque ligne porte une issue (running | success | failed | stopped | orphaned), une durée, une branche git et des métriques agrégées. En mode JSON, les lignes sont diffusées une par une.

Synopsis

ambih history 
ambih history <projet> [--limit N] [--json]

Options

--limit N Nombre de sessions à retourner. 10 par défaut ; borné à [1, 1000].
--json Diffuse un objet JSON par session.

Exemple

bash 
$ambih history web-app --limit 20

ambih diff

Comparaison métrique par métrique entre deux sessions — comme git diff, mais pour la consommation de ressources. Les références de session sont des GUID complets ou des préfixes d'identifiant uniques d'au moins 8 caractères. Chaque ligne porte a, b, delta, delta_percent et une direction (up | down | unchanged | missing).

Synopsis

ambih diff 
ambih diff <session-a> <session-b> [--json]

Options

--json Diffuse un objet JSON par métrique, dans un ordre stable.

Exemple

bash 
$ambih diff a1b2c3d4 e5f6a7b8

ambih exec

Exécution unique d'une commande contre un projet déjà enregistré, avec surveillance complète (courbe de ressources, anomalies, code de sortie). Comme ambih start mais refuse si le projet est déjà en cours (discipline mono-instance) et enregistre la commande comme commande de lancement du projet.

Synopsis

ambih exec 
ambih exec <projet> "<commande>" [--json]

Options

--json Séquence d'événements identique à ambih start --json.

Exemple

bash 
$ambih exec web-app "npm run build" --json

ambih shell

Ouvre un shell interactif attaché à un pty dans le répertoire du projet. Le terminal passe en mode brut : flèches, complétion par tabulation, Ctrl+C et TUI plein écran (vim, htop, less) fonctionnent comme un shell local. Utilise le shell configuré du projet (pwsh sous Windows, zsh sous Mac, bash sous Linux). Refuse si le projet est déjà en cours. Quittez avec exit ou Ctrl+D. Pas de mode --json ; le shell est interactif par nature.

Synopsis

ambih shell 
ambih shell <projet>

Exemple

bash 
$ambih shell web-app

ambih verify

Verdict CI pour une session selon un ensemble de contrôles. Sort avec 0 = succès, 1 = échec, 2 = non concluant — à enchaîner comme eslint --max-warnings 0. Sans --session, cible la dernière session persistée. Tous les contrôles sont cumulatifs.

Synopsis

ambih verify 
ambih verify <projet> [--session <id>] [--check …] [--max-* …] [--json]

Options

--session <id> Cible une session précise au lieu de la dernière.
--check exit-code La session est sortie avec le code 0.
--check no-anomalies Aucune anomalie de niveau Warning+ dans la session.
--check regression Le verdict de santé n'est pas Régression (dernière session seulement).
--max-memory <taille> Mémoire de pointe sous un seuil. Accepte 512MB, 1.5GB, 1024K, 2048.
--max-cpu <pourcent> CPU de pointe sous un seuil. Accepte 80, 80%, 12.5.
--max-duration <durée> Durée totale sous un seuil. Accepte 30s, 5m, 1h, 1500ms.

Exemple

bash 
$ambih verify web-app --check exit-code --check no-anomalies \
    --max-memory 512MB --max-duration 5m

ambih stop

Arrête la session en cours d'un projet. Le projet reste enregistré.

Synopsis

ambih stop 
ambih stop <projet>

Exemple

bash 
$ambih stop web-app

ambih delete

Supprime un projet. Une session en cours est arrêtée au préalable.

Synopsis

ambih delete 
ambih delete | rm <projet>

Exemple

bash 
$ambih rm web-app

ambih ping

Sonde de présence — réussit lorsqu'une instance de l'application Ambih écoute sur le canal IPC de l'utilisateur.

Synopsis

ambih ping 
ambih ping [--json]

Options

--json Émet le résultat de la sonde en JSON.

Exemple

bash 
$ambih ping

ambih help

Affiche l'aide intégrée, ou la version de la CLI avec --version / -v.

Synopsis

ambih help 
ambih help | --help | -h        ambih --version | -v

Exemple

bash 
$ambih --version

Références de projet

Toute commande prenant un <projet> accepte un GUID complet, le nom exact du projet, un préfixe d'identifiant unique, ou un nom insensible à la casse. Les références de session (utilisées par diff et verify --session) acceptent un GUID complet ou un préfixe d'identifiant unique d'au moins 8 caractères — les mêmes préfixes qu'affiche ambih history.

Sortie JSON

Passez --json pour basculer une commande en JSON ligne par ligne (NDJSON) sur stdout. Chaque ligne est un événement structuré avec un discriminant event, un champ schema_version et un horodatage UTC — à passer dans jq ou tout analyseur de flux. Les erreurs antérieures au flux (p. ex. application non lancée) s'affichent en texte brut sur stderr et sortent en non-zéro ; le contrat JSON ne couvre que les événements émis après un démarrage réussi.

bash 
$ambih start "npm test" --json | jq -c 'select(.event == "anomaly")'

Environnement

La CLI communique avec l'application via un canal nommé propre à l'utilisateur (un socket de domaine Unix sous Linux/macOS) ; elle n'ouvre donc aucun port réseau. Si l'application n'est pas lancée, ambih start la démarre en mode barre des tâches et attend le canal avant de diffuser. Installez ou mettez à jour la CLI depuis Paramètres → CLI dans l'application, ce qui ajoute le dossier d'installation au PATH de l'utilisateur.