NOME
gdcloud topic command-conventions - Ajuda complementar para convenções de comando do gdcloud.
DESCRIÇÃO
O design de comandos da CLI gdcloud segue um conjunto comum de princípios e convenções. Este documento descreve esses conceitos em detalhes.
As convenções são metas, e não regras. Para exceções, consulte as informações fornecidas para comandos individuais usando a flag --help.
HIERARQUIA DE COMANDOS
Os comandos da CLI gdcloud são organizados como uma árvore com gdcloud na raiz, grupos de comandos nos nós internos e comandos nos nós folha. Os comandos de grupo podem ser executados, mas apenas para mostrar o texto de ajuda.
Todos os grupos e comandos têm uma flag --help que mostra o texto de ajuda como saída padrão. O texto de ajuda é derivado do executável em execução. Portanto, ele está sempre atualizado, mesmo ao alternar entre várias instalações de lançamento.
LINHA DE COMANDO
Todos os comandos gdcloud seguem o mesmo formato
gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
Os argumentos de flag e posicionais podem ser misturados, mas, para manter a consistência, os posicionais geralmente são mostrados primeiro em ordem, seguidos por flags em qualquer ordem.
NOTAÇÃO DE USO DE COMANDOS
O uso de comandos é uma notação abreviada que contém o nome completo do comando, os argumentos posicionais e os argumentos de flag em ordem de classificação por grupo. Os argumentos opcionais estão entre [ ... ]. Por exemplo:
gdcloud foo bar NAME [--format=FORMAT]
Este é o uso do comando gdcloud foo bar com um argumento posicional NAME obrigatório, um argumento posicional EXTRA opcional e um argumento de flag --format opcional.
Argumentos posicionais
Os argumentos posicionais são ordenados e precisam ser especificados na ordem listada no uso do comando e na lista de definição de argumentos do documento de ajuda.
Argumentos de flag
Os nomes das flags são minúsculos com um prefixo --. Flags com várias palavras usam - (hífen/traço) como separador.
Seguindo a convenção do UNIX, se uma flag for repetida na linha de comando, apenas a ocorrência mais à direita vai entrar em vigor. Nenhum diagnóstico é emitido. Isso facilita a configuração de aliases de comando e scripts de wrapper que fornecem valores de flag padrão, que podem ser substituídos facilmente especificando-os na linha de comando do alias ou do script de wrapper.
Flags booleanas
Embora muitas flags booleanas tenham um valor implícito de false, algumas são true por padrão. A presença de --flag define a flag como true ou false, dependendo do valor implícito pelo nome da flag.
Sinalizações valiosas
As flags não booleanas têm um valor explícito. O valor pode ser especificado colocando-o como o próximo argumento após a flag --flag value.
Se o valor for um número inteiro, ele precisa ser 0 ou maior. Não é possível usar números inteiros negativos.
Saída
A saída padrão é para informações explícitas solicitadas pelo comando.
Dependendo do contexto, pode haver garantias no formato de saída para oferecer suporte à análise determinística. Alguns comandos retornam recursos, que são listados como saída padrão, geralmente usando um formato de tabela específico do comando ou o formato YAML padrão. Além disso, a flag --format pode ser usada para mudar ou configurar esses formatos de saída padrão. Os valores de saída --format de yaml, json e csv garantem que a conclusão bem-sucedida do comando resulte em dados de saída padrão que podem ser analisados usando o formato respectivo. Uma explicação detalhada das funcionalidades da flag --format pode ser encontrada com o comando gdcloud topic formats. Para comandos que não retornam recursos, a saída é definida na flag --help do comando.
O erro padrão é reservado para diagnósticos. Em geral, o formato dos dados de erro padrão pode mudar de versão para versão. Os usuários não podem criar scripts contra conteúdo específico ou até mesmo a existência de saída para o erro padrão. O único indicador de erro confiável é o status de saída.
Nenhum comando da CLI gdcloud pode falhar com uma exceção não detectada. No entanto, se a CLI gdcloud falhar, o stack trace será interceptado e gravado no arquivo de registro, e um diagnóstico de falha será gravado no erro padrão.
Status de saída
O status de saída 0 indica sucesso. Qualquer outro status de saída indica um erro. Os diagnósticos específicos do comando explicam a natureza do erro e como corrigi-lo.