kozou inspect

kozou inspect introspects the PostgreSQL database named in your kozou.config.yaml, builds the Schema Context, and serializes it to stdout (or a file). The Schema Context is the single model that every emitted surface is compiled from: the Admin UI, the MCP context, and the REST surface all read the same shape. Running kozou inspect is the fastest way to see exactly what Kozou derived from your DDL and COMMENT tags before you start a server.

This page is the operator reference for what kozou inspect reads, what it prints, and the flags that control it.

Synopsis

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

With no flags, kozou inspect reads ./kozou.config.yaml, introspects the configured database, and writes the Schema Context as JSON to stdout.

What it does

In execution order:

1. Loads kozou.config.yaml. By default Kozou reads ./kozou.config.yaml; pass --config <path> to point elsewhere. The config supplies the database connection and the schemas to introspect. See kozou.config.yaml.
2. Introspects the database. Kozou connects using the connection string from database.url and reads the tables, columns, types, constraints, and COMMENT text for the configured database.schemas.
3. Loads UI hints, if configured. If uiHints.path is set, the hints file is merged in. UI hints are optional: if the file cannot be loaded, kozou inspect prints a warning to stderr and continues without them. See UI hints.
4. Builds the Schema Context from the introspection result plus any UI hints.
5. Serializes and writes the Schema Context as JSON (default) or YAML, to stdout (default) or to the file given by --output.

What it outputs

The output is the Schema Context — Kozou’s normalized model of your database. It captures the tables, columns, relations, and the meaning Kozou read from your COMMENT tags (@ai, @widget, @policy, @example), combined with any UI hints you configured.

This is the same model that drives every surface Kozou emits:

• the bundled @kozou/svelte-ui Admin UI,
• the @kozou/mcp MCP context exposed to AI agents,
• the REST surface (PostgREST in v0.1; the experimental in-house @kozou/api in the v0.2 line).

Because all three are compiled from this one model, kozou inspect is the ground truth for “what does Kozou think my schema is?” For how each surface is derived from it, see Emitted surfaces.

The default format is pretty-printed JSON. A trailing newline is always appended, so the output is safe to pipe or redirect.

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

The exact JSON shape is an implementation detail of the Schema Context and may grow between releases; treat the fields above as illustrative.

DATABASE_URL

kozou inspect does not read a connection string from a flag. It reads database.url from kozou.config.yaml. The template that ships with Kozou sets that field from the environment:

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

So in the default setup you supply the connection by exporting DATABASE_URL (or setting it inline) before the command. The ${DATABASE_URL} placeholder is expanded from the process environment when the config is loaded.

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

Note that the kozou CLI does not honor a KOZOU_DATABASE_URL variable directly — only the ${DATABASE_URL} placeholder inside the config does the work. If your config hardcodes database.url or reads a different variable, set that instead.

Flags

Flag	Argument	Default	Description
--format	json | yaml	json	Output format. Any other value exits with an error.
--output	<path>	-	Output destination. - writes to stdout; any other value is a file path.
--config	<path>	./kozou.config.yaml	Path to the kozou.config.yaml to load.

Examples

Print the Schema Context as JSON to your terminal:

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

Write the Schema Context to a YAML file by redirecting stdout:

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

Do the same with --output instead of a shell redirect — useful when you want the command itself to own the file:

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

Use a config file that lives somewhere other than the working directory:

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

You can also run it without installing, via npx:

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

When to use it

• Verify a COMMENT change. After you edit a table or column comment — for example, adding an @widget or @ai tag to products.status — run kozou inspect to confirm Kozou read it the way you expected, without starting a server.
• Diff schemas over time. Write the YAML to a file (kozou inspect --format yaml > schema.yaml) and check it into review, or diff two captures to see how a migration changed the derived model.
• Feed tooling. Pipe the JSON into other commands or scripts that need Kozou’s view of the database.

Where to next

• Emitted surfaces — how the Admin UI, MCP, and REST surfaces are each compiled from the Schema Context.
• kozou.config.yaml — the full configuration that kozou inspect reads, including database.url, database.schemas, and uiHints.path.
• kozou dev — start the bundled Admin UI and MCP HTTP server from the same config.
• kozou mcp — expose the Schema Context to AI agents over MCP.