Référence des commandes
Toutes les commandes s'écrivent konsolity <commande> [options]. konsolity help et konsolity <commande> --help affichent l'aide dans la langue du système. Les sorties en --json sont stables et faites pour les scripts ; elles ne contiennent jamais de secret.
Vue d'ensemble
| Commande | Domaine requis | Rôle |
|---|---|---|
login |
Activer la machine (Activer une machine) | |
setup-token |
Créer un jeton longue durée pour la CI et les conteneurs | |
status |
Compte, machine, portée, expiration, état | |
hosts |
hosts |
Hôtes de la portée |
run |
hosts, accès complet |
Exécuter une commande sur un hôte |
snippet list |
snippets |
Snippets de la portée |
snippet run |
snippets + hosts, accès complet |
Lancer un snippet sur un hôte |
sessions |
sessions |
Sessions CLI en cours sur le compte |
sessions end |
sessions |
Mettre fin à une session |
mcp |
mcp |
Serveur MCP local pour Claude Code (MCP local) |
serve |
mcp + intégration Claude |
Traiter les demandes du connecteur Claude (Service) |
service install |
Installer serve comme service système |
|
rotate |
Renouveler le jeton de la machine | |
policy |
Afficher la portée et les règles appliquées | |
logout |
Révoquer la machine et tout effacer localement | |
version |
Version, système, architecture | |
update |
Mettre à jour le binaire (signature vérifiée) |
Une commande hors portée répond scope_denied ; une commande en lecture seule répond read_only.
login
konsolity login [--name <nom>] [--scopes hosts,snippets,sessions,mcp] [--read-only]
Active la machine par un code validé depuis votre compte. Détail et exemples : Activer une machine.
setup-token
konsolity setup-token [--name <nom>] [--scopes <liste>] [--read-only]
Même flux que login, mais affiche une seule fois un jeton ksetup_... au lieu d'enregistrer quoi que ce soit. Fournissez-le ensuite par KONSOLITY_TOKEN. Voir setup-token.
status
konsolity status [--json]
Affiche le compte, le nom et le type de la machine, la portée (domaines, lecture seule ou complète), l'expiration, l'âge du jeton, l'état du serveur et le nombre d'hôtes accessibles.
$ konsolity status
Compte anthony@example.com
Machine build-01 (machine)
Portée hosts, snippets, mcp · accès complet
Expire le 2027-02-08
Jeton renouvelé il y a 3 h
Serveur api.konsolity.com · joignable
Hôtes 4
hosts
konsolity hosts [--json]
Liste les hôtes de la portée : libellé, adresse, utilisateur, groupe. Jamais de mot de passe ni de clé.
$ konsolity hosts
web-01 203.0.113.10 deploy Production
web-02 203.0.113.11 deploy Production
db-01 10.0.0.5 admin Données
run
konsolity run <hôte> [--timeout <secondes>] [--json] -- <commande>
Exécute une commande sur un hôte par SSH : connexion courte dédiée, clé d'hôte épinglée obligatoire, sortie en direct dans le terminal, code retour de la commande distante transmis comme code de sortie de konsolity. <hôte> est le libellé de l'hôte ou son identifiant. Tout ce qui suit -- est la commande, telle quelle.
| Option | Rôle |
|---|---|
--timeout <secondes> |
Délai de la commande, borné par le délai maximal de la machine (60 s par défaut). |
--json |
Une seule sortie JSON à la fin : exit_code, stdout, stderr, duration_ms. |
$ konsolity run web-01 -- systemctl status nginx
● nginx.service - A high performance web server
Active: active (running) since Mon 2026-11-09 08:12:44 UTC
$ echo $?
0
Avant de lancer la commande, la CLI vérifie la portée et les règles, puis inscrit le début au journal : si cette écriture échoue, la commande n'est pas lancée. Une commande destructrice attend votre confirmation :
$ konsolity run db-01 -- "mysql -e 'DROP TABLE sessions_old'"
Commande destructrice : confirmation demandée dans l'app Konsolity.
https://app.konsolity.com/cli/confirm/9f3c2a71
En attente (5 min au plus)...
Autorisée. Exécution.
snippet
konsolity snippet list [--json]
konsolity snippet run <snippet> <hôte> [--timeout <secondes>] [--json]
snippet list affiche les snippets de la portée (nom, groupe). snippet run lance un snippet, tel qu'il est enregistré dans le coffre, sur un hôte de la portée. <snippet> est son nom ou son identifiant. Les mêmes règles que run s'appliquent : journal, confirmation si le contenu est destructeur, code retour transmis.
$ konsolity snippet run "Vider le cache" web-01
Cache cleared.
sessions
konsolity sessions [--follow] [--json]
konsolity sessions end <id>
Liste les sessions CLI en cours sur le compte : machine, commande, depuis quand. --follow garde la liste ouverte et la rafraîchit. sessions end <id> met fin à une session : la commande correspondante est arrêtée en moins de 5 secondes.
$ konsolity sessions
a1b2c3 build-01 run web-01: tail -f /var/log/nginx/access.log depuis 12 min
d4e5f6 laptop mcp depuis 1 h
$ konsolity sessions end a1b2c3
mcp
konsolity mcp
Lance un serveur MCP stdio local, à brancher dans Claude Code :
claude mcp add konsolity -- konsolity mcp
Détail des outils et des limites : MCP local pour Claude Code.
serve
konsolity serve
Traite les demandes du connecteur Claude du compte (claude.ai, app Claude) à la manière de l'app d'ordinateur, mais sans interface, dans la limite de la portée et des règles. Demande le domaine mcp et l'intégration Claude de l'offre Studio. Reste au premier plan ; pour un serveur, installez-la en service.
service install
sudo konsolity service install
Installe konsolity serve comme service système (systemd, launchd ou tâche planifiée Windows). Voir Service et stockage.
rotate
konsolity rotate
Force le renouvellement du jeton de la machine. La rotation est de toute façon automatique toutes les 24 heures. La clé de machine ne change pas.
policy
konsolity policy [--json]
Affiche ce que la machine applique réellement : domaines, lecture seule ou complète, hôtes, snippets, règles de commande, « Toute commande », délai maximal.
logout
konsolity logout
Révoque la machine auprès du serveur, puis efface le jeton, la clé de machine et les copies locales. Pour la réutiliser, il faut une nouvelle activation.
version
konsolity version
Affiche la version, le système et l'architecture.
update
konsolity update
Télécharge la dernière version, vérifie son empreinte SHA-256 et la signature Ed25519 du manifeste, puis remplace le binaire. Installée par apt, dnf ou Homebrew, la CLI vous renvoie vers ce gestionnaire.
Variables d'environnement
| Variable | Rôle |
|---|---|
KONSOLITY_TOKEN |
Jeton longue durée ksetup_... (CI, conteneurs). Remplace les secrets enregistrés. |
Codes de sortie
| Code | Signification |
|---|---|
0 |
Succès. |
| code distant | run et snippet run sortent avec le code retour de la commande distante (par exemple 1 si la commande a échoué sur l'hôte). |
1 |
Erreur générale : machine non activée, réseau injoignable, hôte ou snippet introuvable, ligne de journal non écrite (la commande n'est alors pas lancée), secrets locaux illisibles. |
2 |
Erreur d'utilisation : option inconnue, commande manquante ou trop longue (4 000 caractères au plus), KONSOLITY_TOKEN invalide. |
3 |
Refus : domaine absent de la portée (scope_denied), machine en lecture seule (read_only), aucune règle ne correspond (denied), règles absentes (policy_missing), offre requise (plan_required) ou activation refusée. |
4 |
Commande destructrice non confirmée : refusée dans l'app ou la console, ou sans réponse en 5 minutes. Elle n'a pas été lancée. |
77 |
Machine révoquée, expirée ou utilisée depuis un autre ordinateur (empreinte différente), ou session terminée depuis l'app ou la console : les connexions sont coupées et la commande arrêtée. Sauf pour une simple fin de session, les secrets locaux sont aussi effacés. |