Ces recettes présentent les utilisations courantes du CLI Level depuis un terminal. Remplacez les exemples de noms tels que web-01, Laptops, et Disk cleanup avec les ressources de votre compte Level.

ℹ️ REMARQUE : Exécutez lvl auth status avant une recette pour confirmer le profil actif et l'organisation Level. Préférez les identifiants de ressources lorsqu'un nom correspond à plusieurs enregistrements.

Se connecter et vérifier la session

Démarrer la connexion via le navigateur :

lvl auth login

Confirmer la session active :

lvl auth status

La commande de connexion affiche un code à usage unique et une URL de vérification. Après avoir approuvé l'accès dans votre navigateur, le CLI enregistre la session pour le profil actif.

Lister et filtrer les appareils

Rechercher des noms d'appareils et retourner toutes les pages correspondantes :

lvl device list --search web --limit all

Retourner les mêmes résultats en JSON :

lvl device list --search web --limit all -o json

Utiliser le filtre jq intégré pour sélectionner des champs spécifiques :

lvl device list --search web --limit all --jq '.list[] | {id, name, online}'

--jq implique une sortie JSON. Les résultats de type chaîne s'affichent en texte brut. Les objets et autres valeurs s'affichent en JSON compact, un résultat par ligne.

ℹ️ REMARQUE : Les commandes de liste paginées retournent jusqu'à 100 enregistrements par défaut. Utilisez --limit all uniquement lorsque vous avez besoin de l'ensemble complet des résultats.

Exporter les appareils au format CSV

Exporter les appareils d'un groupe :

lvl device export --group Laptops > devices.csv

L'export écrit le CSV brut sur la sortie standard. Redirigez-le vers un fichier plutôt que d'ajouter -o json.

Vous pouvez utiliser le même schéma pour les alertes et les exécutions d'automatisation :

lvl alert export --status resolved > resolved-alerts.csv
lvl run export --status error > failed-runs.csv

Exécuter un diagnostic en lecture seule sur un appareil de type Unix

L'exemple suivant vérifie l'utilisation du système de fichiers sur un appareil Linux ou macOS :

lvl script run \  --device web-01 \  --command 'df -h' \  --shell bash \  --run-as current_user \  --wait \  -o json

Cette commande crée une exécution de script ad hoc. --wait interroge régulièrement la complétion et inclut la sortie des étapes dans le résultat.

Si vous omettez --wait, le CLI retourne les identifiants d'exécution découverts. Vérifiez une exécution ultérieurement avec :

lvl run get RUN_ID --wait -o json

⚠️ AVERTISSEMENT : Confirmez le système d'exploitation cible avant d'exécuter une commande ad hoc. La création de script et les exécutions ad hoc utilisent par défaut le SYSTEM le paramètre d'exécution en tant que, sauf si vous spécifiez une autre valeur.

Créer et réutiliser un script de diagnostic enregistré

Si vous disposez déjà d'un script Bash vérifié dans os-info.sh, enregistrez-le dans Level :

lvl script create \  --name 'OS info' \  --file ./os-info.sh \  --shell bash \  --run-as current_user \  -o json

Exécuter le script enregistré par son nom :

lvl script run 'OS info' --device web-01 --wait -o json

Remplacer les valeurs de variables enregistrées pour une seule exécution :

lvl script run 'Repair Chrome' --device web-01 --variable channel=stable --variable version=129 --wait -o json

--variable est disponible uniquement lorsque vous exécutez un script enregistré. Répétez --variable <name>=<value> pour chaque remplacement. Vous pouvez identifier une variable par son nom, son identifiant ou son {{reference}}. Les variables que vous ne spécifiez pas utilisent leurs valeurs par défaut enregistrées. Chaque valeur est préservée exactement, y compris une valeur vide, les virgules et les = signes.

Un script enregistré conserve son shell configuré, son délai d'expiration et son paramètre d'exécution en tant que. Lorsque vous exécutez un script enregistré par nom ou par identifiant, n'ajoutez pas de remplacements de shell ou d'exécution en tant que.

Utilisez un identifiant de script lorsque plusieurs scripts portent le même nom.

Prévisualiser une spécification d'automatisation

Exporter une automatisation existante en YAML :

lvl automation spec 'Disk cleanup' > disk-cleanup.yaml

Par défaut, les références à d'autres enregistrements utilisent des identifiants, afin de continuer à identifier les mêmes enregistrements après un renommage. Pour rendre les références de ressources prises en charge plus faciles à lire ou à modifier, ajoutez --names:

lvl automation spec 'Disk cleanup' --names > disk-cleanup.yaml

Le CLI utilise un nom d'affichage uniquement lorsqu'il correspond au même enregistrement. Si le nom est manquant, ambigu ou correspond à un enregistrement différent, l'identifiant reste dans l'export.

Tous les identifiants ne sont pas remplacés. Les références aux actions et variables locales à l'automatisation peuvent rester sous forme d'identifiants. Utilisez cette recette pour examiner ou mettre à jour l'automatisation existante, et non comme une recette complète de clonage ou de migration inter-comptes.

Prévisualiser comment cette spécification modifierait l'automatisation en production :

lvl automation apply -f disk-cleanup.yaml --dry-run -o json

Une exécution à blanc affiche les modifications planifiées sans les appliquer.

Après avoir examiné le fichier et le résultat de l'exécution à blanc, appliquez-le avec :

lvl automation apply -f disk-cleanup.yaml

⚠️ AVERTISSEMENT : L'application d'une spécification reconcilie l'automatisation en production avec le fichier. Une liste de variables, de déclencheurs ou d'actions incluse dans le fichier représente l'état complet ; les entrées existantes absentes de cette liste peuvent donc être supprimées. Omettez une liste entière pour la laisser inchangée. Conservez un export à jour, exécutez --dry-run avant chaque application, et examinez les avertissements.

Créer une automatisation avec des références dans le même fichier

Vous pouvez déclarer des variables et des actions dans une seule spécification, puis les référencer depuis d'autres entrées de ce fichier. Il s'agit d'un workflow de création distinct de celui de l'automatisation existante --names la recette d'export ci-dessus.

Vérifiez les champs de spécification pris en charge par votre CLI installé :

lvl automation schema
lvl automation schema shell waitForOnline restart
lvl automation create --help

Enregistrez ce qui suit sous disk-check.yaml. Cet exemple est destiné aux appareils Linux ou macOS. Il attend que l'appareil soit en ligne, exécute la commande en lecture seule df -h commande, stocke sa sortie dans une variable et crée une alerte Level si la commande échoue.

name: Disk check reference recipe
description: Read disk usage and report command failures.
variables:
  - name: disk_report
    defaultValue: ""
triggers: []
actions:
  - nickname: Wait until online
    actionable:
      waitForOnline: {}
  - nickname: Check disk usage
    onFailure: CONTINUE
    outputVariable: disk_report
    actionable:
      shell:
        command: df -h
        shell: BASH
        runAs: CURRENT_USER
        timeout: 60
  - nickname: Report failure
    conditions:
      - strategy:
          stepStatus:
            id: Check disk usage
            values: [failed]
        valueComparison: EQUAL
    actionable:
      createAlert:
        name: Disk usage check failed
        description: The disk usage command failed. Review the run output.
        severity: WARNING

Confirmez l'organisation avec lvl auth status, examinez le fichier, puis créez l'automatisation :
```
lvl automation create -f disk-check.yaml -o json
```
Cette commande écrit une nouvelle automatisation dans Level. Elle n'exécute pas les actions sur un appareil. La triggers la liste laisse cet exemple sans déclencheurs automatiques. Enregistrez l'identifiant d'automatisation retourné avant d'effectuer des mises à jour ultérieures.

onFailure: CONTINUE permet à l'exécution d'atteindre l'action finale après un contrôle de disque échoué. Sa stepStatus condition signifie que l'action d'alerte ne s'exécute que lorsque Vérifier l'utilisation du disque a échoué.

Règles de référence et de validation

outputVariable: disk_report fait référence à la variable déclarée dans ce fichier. Utilisez la casse exacte du nom de la variable.
Un stepStatus condition peut identifier une action antérieure par son identifiant, son surnom unique ou sa position à partir de zéro. Ici, "actions[1]" identifie Vérifier l'utilisation du disque et peut remplacer son surnom dans la condition. Utilisez la casse exacte du surnom. Les références d'actions doivent rester au sein de cette automatisation. Un resolveAlert de l'action sourceId fait également référence à une action antérieure.
Chaque actionable bloc contient exactement un type d'action. Utilisez les valeurs d'énumération exactement telles qu'elles sont présentées dans le schéma, par exemple BASH, CURRENT_USER, et CONTINUE.
waitForOnline: {} n'a pas de paramètre de délai d'expiration. Un appareil hors ligne attend à cette étape jusqu'à ce qu'il se reconnecte ou que l'exécution soit annulée.
Les noms des ressources externes à la spécification, tels que les scripts enregistrés ou les étiquettes, doivent toujours être résolus dans l'organisation active. Gardez cet exemple autonome séparé du clonage ou de la migration inter-comptes.

Remplacer un type d'action sans déplacer l'étape

Exportez l'automatisation que vous souhaitez modifier. Remplacez AUTOMATION_ID par son identifiant réel et conservez une copie inchangée de l'export :
```
lvl automation spec AUTOMATION_ID > automation-update.yaml
```
Trouvez l'entrée d'action que vous souhaitez remplacer. Conservez son id, sa position dans le actions tableau, et toutes les autres entrées d'action. Remplacez uniquement le actionable bloc. Par exemple, ce fragment transforme l'étape sélectionnée en une pause de 30 secondes :
```
actionable:
  delay:
    duration: 30
```
Il s'agit d'un fragment à insérer dans l'entrée d'action exportée, et non d'un fichier d'application complet. Supprimez l'ancienne clé de type d'action au lieu de conserver les deux types. Revérifiez les variables de sortie et la logique en aval, car le remplacement effectue une opération différente.
Prévisualiser le fichier modifié complet :
```
lvl automation apply -f automation-update.yaml --dry-run -o json
```
Vérifiez les suppressions, remplacements et avertissements inattendus. Conserver l'action à la même position dans le tableau préserve sa position dans l'automatisation. Les conditions de statut d'étape qui référencent l'action remplacée sont redirigées vers son remplacement.
Après avoir examiné le plan, appliquez le fichier :
```
lvl automation apply -f automation-update.yaml
```
Le remplacement possède un nouvel identifiant d'action. Exportez à nouveau l'automatisation avant votre prochaine modification afin d'utiliser les identifiants actuels.

Configurer une action Redémarrage planifiée par l'utilisateur

Pour une action Redémarrage sur Windows ou macOS, utilisez askForApproval avec maxScheduleTime pour permettre à l'utilisateur connecté de choisir une heure de redémarrage dans un délai imparti. Ce qui suit est un actionable fragment pour une entrée d'action dans une spécification complète :

actionable:
  restart:
    askForApproval: true
    question: Save your work and choose a restart time within 4 hours.
    frequency: 900
    maxAttempts: null
    maxTime: null
    maxScheduleTime: 14400

frequency et maxScheduleTime sont en secondes. Cet exemple définit un intervalle de rappel de 15 minutes et une fenêtre de planification de 4 heures. Le temps en veille ou hors tension est pris en compte dans le délai de planification, mais Level ne peut pas redémarrer un appareil éteint à l'heure sélectionnée.

Avec askForApproval: true, fournissez un question et un frequency. Définissez au plus un de maxAttempts, maxTime, et maxScheduleTime. Définir explicitement les limites inutilisées à null efface toutes les limites précédentes lors de la mise à jour d'une action existante. Un maxScheduleTime doit être positif ; null désactive la planification par l'utilisateur.

AVERTISSEMENT : Une action Redémarrage peut interrompre le travail. Les invites destinées aux utilisateurs finaux et la planification sont disponibles sur Windows et macOS. Linux redémarre sans invite d'approbation. Sur Windows et macOS, si aucun utilisateur n'est connecté et qu'aucune heure de redémarrage n'a été choisie, l'action redémarre immédiatement. Examinez Action Redémarrage avant de tester, et utilisez le workflow d'exécution à blanc et de révision du fichier complet ci-dessus avant d'appliquer ces paramètres.

Inspecter les politiques de surveillance

Lister les politiques de surveillance :

lvl monitor policy list --limit all

Obtenir une politique par identifiant ou par nom :

lvl monitor policy get 'Server health' -o json

Exporter sa spécification :

lvl monitor policy spec 'Server health' > server-health.yaml

L'export par défaut utilise des identifiants pour les références à d'autres enregistrements, préservant les mêmes cibles après un renommage. Pour utiliser des noms lisibles pour les références prises en charge à la place, ajoutez --names:

lvl monitor policy spec 'Server health' --names > server-health.yaml

Un nom n'est utilisé que s'il correspond au même enregistrement. Les noms manquants ou ambigus, ou les noms qui correspondent à un enregistrement différent, laissent l'identifiant inchangé ; ainsi, un export nommé peut toujours contenir des identifiants.

Prévisualiser une spécification avant de l'appliquer :

lvl monitor policy apply -f server-health.yaml --dry-run -o json

L'application d'une politique de surveillance reconcilie également la ressource en production. Examinez le résultat de l'exécution à blanc avant de l'appliquer.

Utiliser des références qualifiées par groupe

Les références d'appareils peuvent utiliser un identifiant, un nom d'hôte, un nom, un surnom ou un nom d'hôte qualifié par groupe :

lvl device get 'Servers/web-01'

Les références qualifiées par groupe sont utiles lorsque différents groupes d'appareils contiennent le même nom d'hôte. Si une référence est toujours ambiguë, le CLI s'arrête et liste les correspondances au lieu d'en choisir une.

Inspecter les indicateurs exacts et les formats de sortie

Afficher l'aide normale d'une commande :

lvl script run --help

Afficher la référence générée, y compris le format de sortie JSON :

lvl skill describe script run

Afficher toutes les commandes d'un groupe :

lvl skill describe update

Le CLI installé est la source de vérité pour ses indicateurs et définitions de sortie actuels.

Liste de contrôle de sécurité

Avant d'exécuter une commande qui modifie Level ou un appareil géré :

Confirmez l'organisation active avec lvl auth status.
Confirmez chaque cible par identifiant, nom ou référence qualifiée par groupe.
Examinez intégralement les scripts et les spécifications JSON ou YAML.
Vérifiez si la commande utilise par défaut SYSTEM, installe des mises à jour, redémarre un appareil ou remplace un fichier.
Utilisez --dry-run lorsque disponible.
Utilisez --yes uniquement après avoir examiné l'ensemble complet des ressources sélectionnées.
Vérifiez l'historique des exécutions ou les journaux de mise à jour pour les résultats asynchrones.

Les commandes de suppression définitive requièrent une confirmation dans un terminal interactif et nécessitent --yes lors d'une exécution non interactive. Certaines commandes, notamment le redémarrage et l'arrêt d'un appareil, déclenchent l'action immédiatement sans invite de confirmation.

Exemples et recettes pour le CLI Level