gdcloud topic コマンドの表記規則

名前

gdcloud topic command-conventions - gdcloud コマンドの規則に関する補足ヘルプ。

説明

gdcloud CLI コマンドの設計は、一般的な一連の原則と規則に従っています。このドキュメントでは、これらについて詳しく説明します。

慣例はルールではなく目標です。例外については、--help フラグを使用して個々のコマンドに提供されている情報を参照してください。

コマンドの階層構造

gdcloud CLI コマンドは、ルートに gdcloud、内部ノードにコマンド グループ、リーフノードにコマンドがあるツリーとして編成されています。グループ コマンドは実行可能ですが、ヘルプ テキストの表示にのみ使用されます。すべてのグループとコマンドには、ヘルプテキストを標準出力として表示する --help フラグがあります。ヘルプテキストは実行中の実行可能ファイルから取得されるため、複数のリリース インストールを切り替える場合でも、常に最新の状態が維持されます。

コマンドライン

すべての gdcloud コマンドは同じ形式に従います。

gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...

フラグと位置引数は混在させることができますが、一貫性を保つため、通常は位置引数が順番に最初に表示され、その後にフラグが任意の順序で表示されます。

コマンドの使用表記

コマンドの使用方法は、完全なコマンド名、位置引数、フラグ引数をグループでソートした順序で含む省略表記です。オプションの引数は [ ... ] で囲みます。たとえば、

gdcloud foo bar NAME [--format=FORMAT]

これは、必須の NAME 位置引数、省略可能な EXTRA 位置引数、省略可能な --format フラグ引数を含む gdcloud foo bar コマンドの使用方法です。

位置引数

位置引数は順序付けられており、コマンドの使用方法とヘルプ ドキュメントの引数定義リストに記載されている順序で指定する必要があります。

フラグ引数

フラグ名は小文字で、接頭辞 -- が付いています。複数の単語で構成されるフラグでは、単語の区切り文字として -(ハイフン/ダッシュ)を使用します。UNIX の慣例に従い、コマンドラインでフラグが繰り返された場合は、最も右側のフラグのみが有効になります。診断は出力されません。これにより、コマンド エイリアスとラッパー スクリプトを簡単に設定できます。これらのエイリアスとラッパー スクリプトは、デフォルトのフラグ値を提供します。これらの値は、エイリアスまたはラッパー スクリプトのコマンドラインで指定することで簡単にオーバーライドできます。

ブール値フラグ

多くのブール値フラグの暗黙的な値は false ですが、デフォルトで true になっているものもあります。--flag が存在する場合、フラグの名前が示す値に応じて、フラグが true または false に設定されます。

値付きフラグ

ブール値以外のフラグには明示的な値があります。値は、フラグ --flag value の次の引数として値を指定することで設定できます。

値が整数の場合、0 以上である必要があります。負の整数は使用できません。

出力

標準出力は、コマンドでリクエストされた明示的な情報用です。コンテキストによっては、決定論的解析をサポートするために出力形式の保証が必要になることがあります。特定コマンドはリソースを返します。これらのリソースは通常、コマンド固有のテーブル形式またはデフォルトの YAML 形式を使用して標準出力として表示されます。また、--format フラグを使用して、これらのデフォルトの出力形式を変更または構成できます。yamljsoncsv の出力 --format 値は、コマンドが正常に完了すると、それぞれの形式を使用して解析できる標準出力データが生成されることを保証します。--format フラグの機能の詳細については、gdcloud topic formats コマンドをご覧ください。リソースを返さないコマンドの場合、出力はコマンドの --help フラグで定義されます。標準エラーは診断用に予約されています。一般に、標準エラーデータの形式はリリースごとに変更される可能性があります。ユーザーは、特定のコンテンツや、標準エラーへの出力の存在に対してスクリプトを作成してはなりません。信頼できるエラー指標は終了ステータスのみです。キャッチされない例外でクラッシュする gdcloud CLI コマンドはありません。ただし、gdcloud CLI がクラッシュした場合、スタック トレースがインターセプトされてログファイルに書き込まれ、クラッシュ診断が標準エラーに書き込まれます。

終了ステータス

終了ステータス 0 は成功を示します。その他の終了ステータスはエラーを示します。コマンド固有の診断では、エラーの性質と修正方法が説明されます。