kozou inspect

kozou inspect は kozou.config.yaml で指定された PostgreSQL データベースを検査し、Schema Context を構築して、それを stdout（またはファイル）にシリアライズします。Schema Context は、出力されるすべてのサーフェスがコンパイルされる元となる単一のモデルです。Admin UI、MCP コンテキスト、 REST サーフェスはいずれも同じ形を読み取ります。kozou inspect を実行することは、サーバーを起動する前に、Kozou が DDL と COMMENT タグから何を導出したかを正確に確認する最速の方法です。

このページは、kozou inspect が何を読み取り、何を出力し、どのフラグでそれを制御するかについてのオペレーター向けリファレンスです。

構文

kozou inspect [--format json|yaml] [--output <path>] [--config <path>]

フラグを指定しない場合、kozou inspect は ./kozou.config.yaml を読み取り、設定されたデータベースを検査し、Schema Context を JSON として stdout に書き出します。

動作内容

実行順は次のとおりです。

kozou.config.yaml を読み込みます。 デフォルトでは Kozou は ./kozou.config.yaml を読み取ります。別の場所を指す場合は --config <path> を渡してください。この設定はデータベース接続と検査対象のスキーマを提供します。kozou.config.yaml を参照してください。
データベースを検査します。 Kozou は database.url の接続文字列を使って接続し、設定された database.schemas についてテーブル、カラム、型、制約、COMMENT テキストを読み取ります。
UI hints が設定されていれば読み込みます。 uiHints.path が設定されている場合、hints ファイルがマージされます。UI hints は任意です。ファイルを読み込めない場合、kozou inspect は警告を stderr に出力し、それなしで処理を続行します。UI hints を参照してください。
検査結果と（あれば）UI hints から Schema Context を構築します。
Schema Context を JSON（デフォルト）または YAML として シリアライズして書き出します。 出力先は stdout（デフォルト）または --output で指定されたファイルです。

出力内容

出力は Schema Context です。これは Kozou がデータベースを正規化したモデルです。テーブル、カラム、リレーション、そして Kozou が COMMENT タグ（@ai、@widget、@policy、@example）から読み取った意味を、設定した UI hints と組み合わせて捉えます。

これは、Kozou が出力するすべてのサーフェスを駆動するのと同じモデルです。

同梱の @kozou/svelte-ui Admin UI、
AI エージェントに公開される @kozou/mcp MCP コンテキスト、
REST サーフェス（v0.1 では PostgREST、v0.2 系列では実験的な自作の @kozou/api）。

これら 3 つすべてがこの 1 つのモデルからコンパイルされるため、 kozou inspect は「Kozou は私のスキーマをどう認識しているか」についての基準となる真実です。各サーフェスがこのモデルからどのように導出されるかについては、出力サーフェスを参照してください。

デフォルトの形式は整形された JSON です。末尾の改行は常に追加されるため、出力はパイプやリダイレクトに安全に使えます。

{
  "tables": [
    {
      "name": "products",
      "schema": "public",
      "columns": [
        { "name": "id", "type": "uuid" },
        { "name": "status", "type": "text" }
      ]
    }
  ]
}

正確な JSON の形は Schema Context の実装の詳細であり、リリース間で拡張される可能性があります。上記のフィールドは例示として扱ってください。

DATABASE_URL

kozou inspect はフラグから接続文字列を読み取りません。kozou.config.yaml の database.url を読み取ります。Kozou に同梱されるテンプレートは、このフィールドを環境から設定します。

database:
  url: ${DATABASE_URL}
  schemas: [public]

そのため、デフォルトの設定ではコマンドの前に DATABASE_URL をエクスポート（またはインラインで設定）して接続を供給します。${DATABASE_URL} プレースホルダーは、設定が読み込まれるときにプロセス環境から展開されます。

DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  kozou inspect --format yaml

kozou CLI は KOZOU_DATABASE_URL 変数を直接認識しないことに注意してください。設定内の ${DATABASE_URL} プレースホルダーだけがその役割を果たします。設定が database.url をハードコードしていたり、別の変数を読み取る場合は、そちらを設定してください。

フラグ

フラグ	引数	デフォルト	説明
`--format`	`json \| yaml`	`json`	出力形式。それ以外の値はエラーで終了します。
`--output`	`<path>`	`-`	出力先。`-` は stdout に書き出し、それ以外の値はファイルパスです。
`--config`	`<path>`	`./kozou.config.yaml`	読み込む `kozou.config.yaml` へのパス。

例

Schema Context を JSON としてターミナルに出力します。

DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  kozou inspect

stdout をリダイレクトして Schema Context を YAML ファイルに書き出します。

DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  kozou inspect --format yaml > schema.yaml

シェルのリダイレクトの代わりに --output で同じことを行います。コマンド自体にファイルを管理させたいときに便利です。

DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  kozou inspect --format yaml --output schema.yaml

作業ディレクトリ以外の場所にある設定ファイルを使います。

DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  kozou inspect --config ./config/kozou.config.yaml --format json

npx 経由でインストールせずに実行することもできます。

DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  npx kozou inspect --format yaml > schema.yaml

使うべき場面

COMMENT の変更を検証する。 テーブルまたはカラムのコメントを編集した後 — 例えば products.status に @widget や @ai タグを追加した後 — kozou inspect を実行すれば、サーバーを起動せずに、Kozou が期待どおりに読み取ったかを確認できます。
スキーマを時系列で差分比較する。 YAML をファイルに書き出し（kozou inspect --format yaml > schema.yaml）、それをレビューにコミットするか、 2 つのキャプチャを差分比較して、マイグレーションが導出モデルをどう変えたかを確認します。
ツールに渡す。 JSON を、Kozou のデータベースビューを必要とする他のコマンドやスクリプトにパイプします。

次に読むべきもの

出力サーフェス — Admin UI、MCP、REST の各サーフェスがそれぞれどのように Schema Context からコンパイルされるか。
kozou.config.yaml — kozou inspect が読み取る設定の全体。database.url、database.schemas、uiHints.path を含みます。
kozou dev — 同じ設定から、同梱の Admin UI と MCP HTTP サーバーを起動します。
kozou mcp — Schema Context を MCP 経由で AI エージェントに公開します。