NOMBRE
gdcloud topic command-conventions: ayuda complementaria para las convenciones de comandos de gdcloud.
DESCRIPCIÓN
El diseño de los comandos de la CLI 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 cada comando mediante la marca --help.
JERARQUÍA DE COMANDOS
Los comandos de la CLI gdcloud se organizan en forma de á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 una marca --help que muestra el texto de ayuda como salida estándar. El texto de ayuda se deriva del ejecutable en ejecución, por lo que siempre está actualizado, incluso cuando se cambia entre varias instalaciones de versiones.
LÍNEA DE COMANDOS
Todos los comandos de gdcloud siguen el mismo formato
gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
Los argumentos de marca y posicionales se pueden mezclar, pero, para mantener la coherencia, los posicionales se suelen mostrar primero, 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 indicado en la lista de definiciones de argumentos del documento de ayuda y uso de comandos.
Argumentos de 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 se aplicará la que esté 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 a la marca el valor true o false, según el valor implícito en el nombre de la marca.
Marcas valoradas
Las marcas no booleanas tienen un valor explícito. El valor se puede especificar colocándolo 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 para 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 con un formato de tabla específico del comando o con el formato YAML predeterminado. Además, la marca --format se puede usar para cambiar o configurar estos formatos de salida predeterminados. Los valores de salida yaml, json y csv de --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, la salida 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 CLI gdcloud debería fallar con una excepción no detectada. Sin embargo, si la CLI gdcloud falla, el rastreo de la pila se intercepta y se escribe en el archivo de registro, y se escribe un diagnóstico de fallo en el error estándar.
Estado de salida
El estado de salida 0 indica que se ha completado correctamente. Cualquier otro estado de salida indica un error. Los diagnósticos específicos de cada comando explicarán la naturaleza del error y cómo corregirlo.