NOMBRE
gdcloud topic command-conventions: ayuda complementaria sobre las convenciones de los comandos de gdcloud.
DESCRIPCIÓN
El diseño de los comandos de la CLI de gdcloud sigue un conjunto de principios y convenciones comunes. En este documento se describen en detalle.
Las convenciones son objetivos, no reglas. Para ver las excepciones, consulta la información proporcionada para los comandos individuales mediante la marca --help.
JERARQUÍA DE COMANDOS
Los comandos de la CLI de gdcloud se organizan como un árbol con gdcloud en la raíz, grupos de comandos en los nodos internos y comandos en los nodos hoja. Los comandos de grupo se pueden ejecutar, pero solo para mostrar el texto de ayuda.
Todos los grupos y comandos tienen un indicador --help que muestra el texto de ayuda como salida estándar. El texto de ayuda se deriva del archivo ejecutable en ejecución, por lo que siempre está actualizado, incluso cuando se cambia entre varias instalaciones de lanzamiento.
LÍNEA DE COMANDOS
Todos los comandos de gdcloud siguen el mismo formato
gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
Los argumentos de marca y de posición se pueden mezclar, pero, por coherencia, los de posición suelen mostrarse primero en orden, seguidos de las marcas en cualquier orden.
NOTACIÓN DE USO DE COMANDOS
El uso de comandos es una notación abreviada que contiene el nombre completo del comando, los argumentos posicionales y los argumentos de marca en orden de grupo. Los argumentos opcionales se incluyen entre [ ... ]. por ejemplo:
gdcloud foo bar NAME [--format=FORMAT]
Este es el uso del comando gdcloud foo bar con un argumento posicional NAME obligatorio, un argumento posicional EXTRA opcional y un argumento de marca --format opcional.
Argumentos posicionales
Los argumentos posicionales están ordenados y deben especificarse en el orden que se indica en la lista de definiciones de argumentos del uso del comando y del documento de ayuda.
Argumentos de las marcas
Los nombres de las marcas están en minúsculas y tienen el prefijo --. Las marcas de varias palabras usan - (guion) como separador de palabras.
Siguiendo la convención de UNIX, si se repite una marca en la línea de comandos, solo tendrá efecto la aparición más a la derecha. No se emite ningún diagnóstico. De esta forma, es fácil configurar alias de comandos y secuencias de comandos de envoltorio que proporcionen valores de marca predeterminados. Estos valores se pueden anular fácilmente especificándolos en la línea de comandos del alias o de la secuencia de comandos de envoltorio.
Marcas booleanas
Aunque muchas marcas booleanas tienen un valor implícito de false, algunas son true de forma predeterminada. La presencia de --flag asigna el valor true o false a la marca, según el valor implícito en el nombre de la marca.
Marcas con valor
Las marcas no booleanas tienen un valor explícito. El valor se puede especificar colocando el valor como el siguiente argumento después de la marca --flag value.
Si el valor es un número entero, debe ser 0 o superior. No se aceptan números enteros negativos.
Salida
La salida estándar es la información explícita solicitada por el comando.
En función del contexto, puede haber garantías sobre el formato de salida para admitir el análisis determinista. Algunos comandos devuelven recursos, que se muestran como salida estándar. Normalmente, se utiliza un formato de tabla específico del comando o el formato YAML predeterminado. Además, se puede usar la marca --format para cambiar o configurar estos formatos de salida predeterminados. Los valores de salida yaml, json y csv --format garantizan que, si el comando se completa correctamente, se obtendrán datos de salida estándar que se pueden analizar con el formato correspondiente. Puedes consultar una explicación detallada de las funciones de la marca --format con el comando gdcloud topic formats. En el caso de los comandos que no devuelven recursos, el resultado se define en la marca --help del comando.
El error estándar se reserva para los diagnósticos. En general, el formato de los datos de error estándar puede cambiar de una versión a otra. Los usuarios no deben crear secuencias de comandos para contenido específico ni para la existencia de resultados en el error estándar. El único indicador de error fiable es el estado de salida.
Ningún comando de la interfaz de línea de comandos de gdcloud debería fallar con una excepción no detectada. Sin embargo, si la CLI de gdcloud falla, se interceptará el seguimiento de pila y se escribirá en el archivo de registro. Además, se escribirá un diagnóstico de fallo en el error estándar.
Estado de salida
El estado de salida 0 indica que la operación se ha realizado correctamente. Cualquier otro estado de salida indica un error. Los diagnósticos específicos de los comandos explicarán la naturaleza del error y cómo corregirlo.