NOM
gdcloud topic command-conventions - Supplementary help for gdcloud command-conventions.
DESCRIPTION
La conception des commandes gdcloud CLI suit un ensemble commun de principes et de conventions. Ce document les décrit en détail.
Les conventions sont des objectifs plutôt que des règles. Pour toute exception, consultez les informations fournies pour les commandes individuelles à l'aide de l'option --help.
HIÉRARCHIE DES COMMANDES
Les commandes gdcloud CLI sont organisées sous forme d'arborescence, avec gdcloud à la racine, des groupes de commandes dans les nœuds internes et des commandes dans les nœuds feuilles. Les commandes de groupe sont exécutables, mais uniquement pour afficher le texte d'aide.
Tous les groupes et toutes les commandes comportent un indicateur --help qui affiche le texte d'aide en tant que sortie standard. Le texte d'aide est dérivé de l'exécutable en cours d'exécution. Il est donc toujours à jour, même lorsque vous passez d'une installation à une autre.
LIGNE DE COMMANDE
Toutes les commandes gdcloud suivent le même format.
gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
Les arguments d'indicateur et positionnels peuvent être mélangés, mais par souci de cohérence, les arguments positionnels sont généralement affichés en premier dans l'ordre, suivis des indicateurs dans n'importe quel ordre.
NOTATION D'UTILISATION DES COMMANDES
L'utilisation des commandes est une notation abrégée qui contient le nom complet de la commande, les arguments positionnels et les arguments d'indicateur dans l'ordre de tri des groupes. Les arguments facultatifs sont placés entre [ ... ]. Exemple
gdcloud foo bar NAME [--format=FORMAT]
Il s'agit de l'utilisation de la commande gdcloud foo bar avec un argument positionnel NAME obligatoire, un argument positionnel EXTRA facultatif et un argument d'option --format facultatif.
Arguments positionnels
Les arguments positionnels sont ordonnés et doivent être spécifiés dans l'ordre indiqué dans la liste de définition des arguments de la documentation d'aide et d'utilisation des commandes.
Arguments des indicateurs
Les noms des indicateurs sont en minuscules et commencent par le préfixe --. Les indicateurs comportant plusieurs mots utilisent - (tiret) comme séparateur de mots.
Conformément à la convention UNIX, si un indicateur est répété sur la ligne de commande, seule l'occurrence la plus à droite prend effet. Aucun diagnostic n'est émis. Il est ainsi facile de configurer des alias de commande et des scripts wrapper qui fournissent des valeurs d'indicateur par défaut. Ces valeurs peuvent être facilement remplacées en les spécifiant sur la ligne de commande de l'alias ou du script wrapper.
Options booléennes
Alors que de nombreux indicateurs booléens ont une valeur implicite de false, certains sont définis sur true par défaut. La présence de --flag définit l'indicateur sur true ou false, en fonction de la valeur impliquée par le nom de l'indicateur.
Indicateurs avec valeur
Les indicateurs non booléens ont une valeur explicite. La valeur peut être spécifiée en la plaçant comme argument suivant après l'indicateur --flag value.
Si la valeur est un nombre entier, elle doit être supérieure ou égale à 0. Les nombres entiers négatifs ne sont pas acceptés.
Sortie
La sortie standard est destinée aux informations explicites demandées par la commande.
Selon le contexte, il peut exister des garanties sur le format de sortie pour permettre une analyse déterministe. Certaines commandes renvoient des ressources. Ces ressources sont listées en tant que sortie standard, généralement à l'aide d'un format de tableau spécifique à la commande ou du format YAML par défaut. De plus, l'option --format peut être utilisée pour modifier ou configurer ces formats de sortie par défaut. Les valeurs --format de sortie yaml, json et csv garantissent qu'une commande exécutée avec succès génère des données de sortie standard qui peuvent être analysées à l'aide du format respectif. Pour obtenir une explication détaillée des fonctionnalités de l'option --format, utilisez la commande gdcloud topic formats. Pour les commandes qui ne renvoient pas de ressources, la sortie est définie dans l'indicateur --help de la commande.
L'erreur standard est réservée aux diagnostics. En général, le format des données d'erreur standard peut changer d'une version à l'autre. Les utilisateurs ne doivent pas créer de scripts pour des contenus spécifiques ni même pour l'existence d'une sortie vers l'erreur standard. Le seul indicateur d'erreur fiable est l'état de sortie.
Aucune commande gdcloud CLI ne doit planter avec une exception non interceptée. Toutefois, si la CLI gdcloud plante, la trace de pile est interceptée et écrite dans le fichier journal, et un diagnostic d'erreur est écrit dans l'erreur standard.
État de sortie
Le code de sortie 0 indique que l'opération a réussi. Tout autre code de sortie indique une erreur. Les diagnostics spécifiques aux commandes expliquent la nature de l'erreur et comment la corriger.