出力形式

すべての uip コマンドは、stdout に 1 つの構造化エンベロープを出力します。エンベロープのスキーマは、ターミナルで読み取る場合でも、 jqにフィードする場合でも、パイプラインから使用する場合でも同じです。このエンベロープのレンダリングは、 json (デフォルト)、 table、 yaml、 plainの 4 つのフォーマットで異なります。--output で切り替え、--output-filterでフィルター処理します。

封筒

成功：

{
  "Result": "Success",
  "Code": "FolderList",
  "Data": [
    {
      "Key": "9f2b3c…-…",
      "Name": "Shared",
      "Path": "Shared",
      "Type": "Standard"
    }
  ]
}

失敗：

{
  "Result": "ValidationError",
  "Message": "Unknown option '--folder-pth'. Did you mean '--folder-path'?",
  "Instructions": "Run 'uip or folders list --help' to see valid options.",
  "Log": "/var/log/uip/2026-04-24.log"
}

フィールド:

• Result — 結果のカテゴリ。Success 成功について。 Failure、 ConfigError、 AuthenticationError、 ValidationError、または TimeoutError (障害発生時)。終了コードに直接マップします。
• Code — コマンド固有の成功識別子。メジャーバージョン(FolderList、 SolutionPack、 JobStarted、 SkillsInstallなど)内で安定しています。
• Data — コマンドのペイロード。Shape はコマンド固有です。正確なフィールドについては、各コマンドのリファレンスページを参照してください。
• Message、 Instructions — 失敗時に存在します。Message 人間が読めるエラーです。 Instructions 、ユーザーまたはオペレーターに何をすべきかを指示します。
• Context — オプションの失敗の詳細(HTTPステータス、要求IDなど)。
• Log — --log-file アクティブな場合、すべてのエンベロープに含まれるログ ファイルへのパス。

エンベロープ自体は 、マイナーバージョン間で安定しています。Dataの形状はコマンド固有であり、進化する可能性があります — バージョニングと安定性を参照してください。

4つのフォーマット

JSON (既定)

uip or folders list

{
  "Result": "Success",
  "Code": "FolderList",
  "Data": [
    { "Key": "9f2b3c…", "Name": "Shared", "Path": "Shared", "Type": "Standard" },
    { "Key": "a4b8f1…", "Name": "Finance", "Path": "Finance", "Type": "Standard" }
  ]
}

既定のパラメーターは、任意の JSON コンシューマー (jq、 --output-filter、スクリプト、AI エージェント) で解析可能であり、バージョン間で決定論的であるためです。端末では問題なく読みます。きれいに印刷された表の場合は、 --output tableに切り替えます。

表

uip or folders list --output table

Key         Name       Path      Type
9f2b3c…     Shared     Shared    Standard
a4b8f1…     Finance    Finance   Standard

実際の端末では色分けされ、縁取られています (stdout が TTY でない場合、色は抑制されます)。各コマンドは、表ビューに最も役立つ と思われる列 を選択しますが、 Data のすべてのフィールドが必ずしも表示されるとは限りません。フィールド全体が揃うようにするには、JSON または YAML を使用します。

表の出力を解析しないでください。列の幅、境界線、さらには列のセットも、マイナーバージョン間で変更される可能性があります。人間が読むためのものです。

YAML

uip or folders list --output yaml

Result: Success
Code: FolderList
Data:
  - Key: 9f2b3c…
    Name: Shared
    Path: Shared
    Type: Standard
  - Key: a4b8f1…
    Name: Finance
    Path: Finance
    Type: Standard

jsonと同じエンベロープのリテラル YAML シリアル化。ツールがYAML(Ansible、Kubernetesマニフェスト、一部のCIプラットフォーム)を好む場合、または2つの実行を目視で比較していて、YAMLがスキャンしやすい場合に便利です。

plain

uip or folders list --output plain

Data[0].Key=9f2b3c…
Data[0].Name=Shared
Data[0].Path=Shared
Data[0].Type=Standard
Data[1].Key=a4b8f1…
Data[1].Name=Finance
Data[1].Path=Finance
Data[1].Type=Standard

1 行あたり 1 つの path=value 。パスは、エンベロープへのドット表記の JMESPath のようなキーです。jqを持たないマシン上のシェル ループに便利です:

uip or folders list --output plain | grep -E '\.Name=' | cut -d= -f2

--output-filterによるフィルタリング

--output-filter は JMESPath 式を受け入れます。フォーマットする前に完全なエンベロープで実行されるため、フィルター出力は --output 生成したフォーマットを継承します。

いくつかの一般的なパターン:

# just the Data array
uip or folders list --output-filter "Data"

# project specific fields
uip or folders list --output-filter "Data[*].{name: Name, path: Path}"

# count
uip or folders list --output-filter "length(Data)"

# first match
uip or folders list --all --name Shared --output-filter "Data[0]"

# flat list of names
uip or folders list --output-filter "Data[*].Name" --output plain

形式が正しくない式は、コマンドを実行する前に ValidationError (終了コード 3) で終了するため、タイプミスによって API 呼び出しが無駄になることはありません。フラグ全体については、グローバルオプション — --output-filter を参照してください。

ストリームの分離

--output は stdout のみを制御します。他のすべての形式の出力は、形式に関係なく stderr に送られます。

• ログ行 ( --log-level 制御するもの)。
• 進行状況インジケーター (スピナー、ツールの自動インストール中のダウンロード バー)。
• 無効なフラグを検出したときにホストによってレンダリングされるエラー テキスト。

つまり、パイプラインは診断を失うことなく、クリーンな出力をファイルにキャプチャできます。

uip or folders list > folders.json 2> uip.log

CIでは、それらを個別にリダイレクトして、データストリームからANSIまたはプログレスアーティファクトを削除することなくログをgrep可能にします。

色と TTY の検出

table形式では、stdout が対話型端末(isTTY)の場合にのみ ANSI カラーコードが出力されます。ファイルまたは別のプロセスにパイプする場合、または TTY を無効にする CI ランナーで実行する場合、テーブル出力はエスケープ コードのないプレーン テキストです。現在、色を強制的にオンまたはオフにするフラグはありません—TTY検出に頼ってください。

他の形式(json、 yaml、 plain)は色を放出しません。

形式を選択する

ユースケース	推奨フォーマット
ターミナルでの読み取り	--output table
スクリプティング (jq、シェルパイプライン)	--output json (既定)
Ansible/Kubernetes の統合	--output yaml
grep-なしのフレンドリーなフラット出力 jq	--output plain
AI コーディングエージェント	--output json (既定) にフォーカスを絞って抽出するための --output-filter
ステップ間で値を渡す CI パイプライン	--output json を --output-filterで使用し、単純なケースの場合は --output plain

参照

• グローバル オプション — --output、 --output-filter、 --log-level、 --log-file フラグです。
• 終了コード — Result からプロセス終了コードへのマッピング。
• スクリプトパターン — CI でのリトライ、ポーリング、安全な JSON 抽出。
• バージョン管理と安定性 — semver での「安定した JSON エンベロープ」の意味。