CLI reference

Every command accepts --project-dir <path> (default: the current directory) and --help. The one exception is init, which takes the directory as a positional argument, since there is no project yet.

ontologiq --version

Authoring

`ontologiq init [directory]`

Scaffolds a working example project — a small e-commerce ontology on DuckDB with seed data, so build produces something to look at immediately.

Refuses to overwrite existing files, and refuses a path that exists and is not a directory.

ontologiq init shop

`ontologiq new object <name>`

Scaffolds objects/<name>.yml with the required fields filled in and the optional blocks present as comments. The name must be snake_case: it becomes both a SQL identifier and part of an MCP tool name.

ontologiq new object invoice

Compiling

`ontologiq validate`

Parses every file, resolves every cross-reference and checks every expression. Touches no database.

It reports all problems in one run, each with file, line and column, and exits non-zero if any is an error. Among the things it catches: unknown relation targets, circular property definitions, state names misspelled inside a precondition, approval.when referencing something that is not a parameter, effect URLs referencing a non-identity placeholder, duplicate YAML keys, and MCP tool-name collisions.

objects/order.yml:32:15: actions.0.requires: 'oepn' is not a declared state
of order (declared: disputed, fulfilled, open)

`ontologiq compile`

Runs validate, then writes target/:

Artefact	Contents
`views/<object>.sql`	The SELECT for each object, in the adapter’s dialect, every identifier quoted
`catalog.json`	Objects, properties (with `sensitive`), states, resolved relations, actions with their governance
`mcp/manifest.json`	The tools an agent will see

Touches no database. target/ is generated output: never edit it, and keep it gitignored.

Applying

`ontologiq seed`

Applies the SQL files listed under seeds: in ontologiq.yml. These are dev and demo fixtures, not a migration system: they are your own dialect-specific SQL, idempotency is your responsibility (write CREATE OR REPLACE), and they run only when you ask.

Statements are split on top-level semicolons and executed one by one, so a failure names the file and the statement — the script is never re-rendered, so your SQL reaches the database byte for byte.

`ontologiq run`

Creates or replaces one view per object through the adapter.

run never executes seeds. Routine commands run no user-supplied write SQL; that is what makes run safe to point at a real warehouse.

`ontologiq build`

validate → compile → seed → run. The one command for the inner loop. (It will also run test once declared checks land; the contract is stated now so behaviour does not change under you later.)

Inspecting

`ontologiq show <object> --key <value>`

Prints one record: identity, resolved properties, computed state, and the actions the object accepts with their governance.

ontologiq show order --key 102

Single-column identities only, for now.

`ontologiq debug`

Loads the config and opens an adapter connection. The first thing to run when something is wrong.

Serving

`ontologiq serve`

Serves the ontology to AI agents over MCP on stdio. See the MCP reference for the tools and security model for what is enforced.

Flag	Effect
`--role <name>`	The role asserted for policy checks. Also read from `ONTOLOGIQ_ROLE`. Without it, `propose_` tools are not exposed at all.
`--read-only`	Expose only the read tools, even with a role.
`--allow-auto-effects`	Permit actions declaring no approval requirement to execute. Off by default.
`--allow-insecure-effects`	Permit plain-http effect URLs. Off by default; localhost is always allowed.

Diagnostics go to stderr, because stdout is the JSON-RPC channel.

Governing

`ontologiq approvals list`

Pending proposals: what was proposed, by which role, when, and when it expires. Values are rendered as JSON so nothing a model supplied can forge a line on your screen.

`ontologiq approvals approve <id>`

Approves a proposal and executes its effect. Deliberately outside the MCP surface: an agent must never be able to sign off its own proposal.

Before firing it re-verifies the arguments against the digest taken when the proposal was made, and re-evaluates the precondition — hours pass, and records move.

Flag	Effect
`--note <text>`	Recorded in the audit trail.
`--force`	Approve even though the ontology changed since the proposal. Without it, a changed ontology is refused.
`--allow-insecure-effects`	As for `serve`.

`ontologiq approvals reject <id>`

Rejects a pending proposal. Terminal: a rejected proposal can never be approved.

`ontologiq audit`

The audit trail, newest last. --proposal <id> narrows it to one proposal, --limit <n> bounds the output.

The log is append-only, enforced by database triggers. That stops accidental code, not an operator with write access to the file — see security.

Not yet implemented

ontologiq test is declared and exits non-zero: the check syntax lands later in the alpha. See the roadmap.