NAME
gdcloud topic command-conventions - Supplementary help for gdcloud command-conventions.
DESCRIÇÃO
O design de comandos da CLI gdcloud segue um conjunto comum de princípios e convenções. Este documento os descreve em detalhes.
As convenções são metas, 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 são executáveis, 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, então ele está sempre atualizado, mesmo ao alternar entre várias instalações de versão.
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 consistência, os posicionais geralmente são mostrados primeiro em ordem, seguidos por flags em qualquer ordem.
NOTAÇÃO DE USO DE COMANDO
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 classificada por grupo. Os argumentos opcionais são incluídos em [ ... ]. 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 na lista de definição de argumentos do documento de uso e ajuda do comando.
Argumentos de flag
Os nomes das flags são minúsculos com um prefixo --. As flags de várias palavras usam - (hífen/traço) como separador de palavras.
Seguindo a convenção UNIX, se uma flag for repetida na linha de comando, apenas a ocorrência mais à direita terá efeito. Nenhum diagnóstico é emitido. Isso facilita a configuração de aliases de comando e scripts de wrapper que fornecem valores de flag padrão, valores 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.
Flags com valores
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 precisará 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, e esses recursos 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 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 dos recursos 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 com conteúdo específico ou até mesmo com 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.