Reference

Commandes CLI

Commandes publiques, résolution des alias et disponibilité selon le contexte.

Syntaxe générale

xbee <commande> [sous-commande] [options] [arguments]
xbee [options] <alias-de-pack> [arguments]

xbee up --log debug
xbee --stack mvn clean install  # mvn est ici un alias de pack installé

L’arbre CLI dépend du répertoire courant. Une commande comme up est disponible dans un pack ou un environnement, mais pas dans un répertoire ordinaire. XBee résout les commandes valides pour le contexte, puis tente d’interpréter l’argument comme un alias de pack installé.

Commandes disponibles partout sur l’hôte

Voir Configuration globale pour les sous-commandes de config.

Créer un pack

La commande canonique est new pack; new p est son alias court :

xbee new pack [NOM...]

Sans nom, elle transforme le répertoire courant en pack. Avec un ou plusieurs noms, elle crée les répertoires correspondants.

xbee new pack application
xbee new pack --type builder application-builder

Créer un environnement

La commande canonique est new environment; new env et new e sont des alias :

xbee new environment [NOM...]
xbee new env

Sans nom, elle crée xbee-env.yaml dans le répertoire courant. Avec un ou plusieurs noms, elle crée autant de répertoires d’environnement.

Depuis un pack, l’environnement généré référence le pack courant et utilise nécessairement le provider Docker interne. Depuis un répertoire ordinaire, il contient un hôte système nu et peut cibler un provider explicite.

xbee new env --provider qemu --system ubuntu:26.04 local-vm

Créer un descripteur d’installation

new install (alias new i) crée un fichier xbee-install.yaml minimal dans le répertoire courant :

xbee new install

Si le répertoire possède déjà ce descripteur, la commande ne le remplace pas. Voir xbee-install et Dev Containers pour son modèle d’utilisation.

Gérer les packs hors abstraction

Dans un répertoire qui n’est ni un pack ni un environnement :

xbee info <origine>
xbee install <origine...>
xbee remove <origine...>
xbee edit <origine>
xbee enter <origine>
xbee pack <origine...>

install, remove, enter et pack acceptent les options de variables du modèle. install, enter et pack permettent aussi de choisir --system. Avec pack --provider <nom>, XBee construit le bundle d’un provider compatible tel que Firecracker, Cloud Hypervisor ou QEMU.

Exécuter une commande exposée par un pack

Après xbee install, une entrée de la section command du pack devient un alias :

xbee [options] <alias> [arguments]
xbee --name tom catalina run

Si le container nommé existe, XBee exécute la commande dedans. Sinon, il crée un nouveau container à partir de l’image du pack.

Commandes d’un pack

Dans un répertoire contenant xbee-pack.yaml :

Un pack de type builder expose aussi xbee build. Les commandes show ne sont pas ajoutées lorsque le même répertoire est à la fois un pack et un environnement.

Options principales de pack

xbee pack                         # réutilise les artefacts valides
xbee pack --force-system          # reconstruit la couche système
xbee pack --force-provision       # rejoue le provisionnement du pack
xbee pack --rebuild-builders      # reconstruit les artefacts builders
xbee pack --no-builder-cache
xbee pack --no-remote-builder-cache
xbee pack --no-remote-cache
xbee pack --plan                  # affiche le plan sans mutation

L’option --system <origine> de xbee pack hors abstraction choisit le pack système ; elle ne signifie pas « reconstruire la couche système ».

Sous-commandes builder

xbee builder list [--json]
xbee builder graph [--json]
xbee builder inspect <sélecteur> [--json]
xbee builder build <sélecteur>
xbee builder clean [<sélecteur>] [--all] [--force]
xbee builder push <sélecteur>
xbee builder pull <sélecteur>
xbee builder remote inspect <sélecteur>
xbee builder remote clean <sélecteur>

Voir Builders et artefacts pour les caches locaux et distants.

Commandes d’un environnement

Dans un répertoire contenant xbee-env.yaml :

enter peut omettre l’instance seulement si l’environnement n’en développe qu’une. Les opérations déclarées dans operate deviennent également des commandes directement exécutables par leur nom.

Suppression et ressources persistantes

xbee delete --force
xbee admin delete volume --force data backup
xbee admin delete pack --host application --force
xbee admin delete system --host application --force
xbee admin delete all --force

delete supprime les hosts. Le cycle de vie exact des volumes externes dépend du provider ; avec les providers microVM locaux, ils sont conservés jusqu’à admin delete volume.

Plan, état et adoption

xbee plan
xbee plan --json
xbee plan --state
xbee state show
xbee state refresh
xbee adopt --plan
xbee adopt
xbee adopt --force

plan est en lecture seule. --state ajoute l’inventaire Docker ou provider au plan. adopt --plan liste les ressources historiques dont la propriété peut être vérifiée, sans les modifier. adopt demande confirmation ; --force rend cette étape non-interactive sans contourner les contrôles de propriété.

Disponibilité par contexte

doctor, config, new et version restent disponibles dans tous ces contextes sur la machine hôte. Les commandes techniques utilisées à l’intérieur des containers ou des VM ne font pas partie de l’interface publique.

Voir Cycle de vie et adoption pour les garanties de sécurité et VM locales et microVM pour les hyperviseurs locaux.