CLI reference

The Docker image ships a single midplane binary. With no subcommand it runs the MCP server. Run the other (operator) commands inside the container with docker exec.

docker exec midplane midplane policy validate /etc/midplane/policy.yaml
docker exec midplane midplane audit denies
docker exec midplane midplane doctor

Command	What it does
`server`	Run the MCP server (the default, the image entrypoint).
`init`	Interactive setup wizard: introspect the database and write a policy.
`query`	Send one statement through the server as an agent would.
`doctor`	Preflight and smoke checks: config, policy, DB connectivity, audit, canary.
`policy`	Author, validate, lint, and dry-run a policy file (`init`/`validate`/`lint`/`test`).
`audit`	Read the local audit log (`tail`/`since`/`denies`/`show`/`stats`).

Output convention. Every command prints human-readable colored output on a TTY and JSON lines when piped. --json / --pretty force one or the other; color respects NO_COLOR.

`midplane server`

Run the MCP server. This is the default command, run by the image entrypoint with no arguments. Reads configuration from environment variables (DATABASE_URL, MIDPLANE_POLICY_FILE, PORT, MIDPLANE_TRANSPORT, …) and serves the MCP endpoint at /mcp.

midplane            # runs the server
midplane server     # explicit form

`midplane init`

Interactive setup wizard. Connects with DATABASE_URL (or a masked prompt; the DSN is never echoed or written), introspects information_schema. You pick per-table read_write grants and denys; it writes a schema-validated, linted policy file and prints the docker command, agent MCP config, and verification steps.

Flag	Purpose
`--url <dsn>`	The database to introspect. Defaults to `DATABASE_URL`.
`-o`, `--out <file>`	Where to write the policy file.

midplane init     # needs a TTY

Synopsis: midplane init [--url <dsn>] [-o <file>]

init needs a TTY. In a script or CI, use midplane policy init instead.

`midplane query`

Send one statement through the server’s full policy and audit pipeline, over Streamable HTTP, as an agent would. Calls stamp agent_name=midplane-cli on their audit rows. One shot, no REPL.

Flag	Purpose
`--sql "<query>"`	The statement to send, or pass it as a bare positional.
`--intent "<why>"`	Audit intent recorded for the call.
`--server <url>`	Server to call. Defaults to `http://localhost:$PORT/mcp`.
`--stdio`	Spawn a child `midplane server` over stdio instead of calling an HTTP server.
`--database <name>`	Target database on a multi-database server.
`--json`	Print the raw result JSON. Default when piped.

docker exec midplane midplane query --sql "SELECT 1"
docker exec midplane midplane query --sql "DELETE FROM users" --intent "verify the policy blocks this"

Synopsis: midplane query --sql "<query>" [--intent "<why>"] [--server <url> | --stdio] [--database <name>] [--json] Exit codes: 0 on ALLOW; 1 on DENY or error; 2 on a usage error.

`midplane doctor`

Preflight and smoke checks in boot order: env config, policy file (validate plus the policy lint findings), per-database connectivity (SELECT 1), the audit store, /health, and an end-to-end MCP canary (a SELECT 1 through the query tool).

Flag	Purpose
`--server <url>`	The running server. Defaults to `http://localhost:$PORT`.
`--no-canary`	Skip the end-to-end MCP query.
`--json`	Emit `{ ok, checks }` instead of the text report.

docker exec midplane midplane doctor

Synopsis: midplane doctor [--server <url>] [--no-canary] [--json] Exit codes: any FAIL exits nonzero; warnings don’t.

`midplane policy`

Author, validate, lint, and dry-run a MIDPLANE_POLICY_FILE — without hand-editing YAML blind or connecting an agent. Four subcommands, run in order for a typical author flow:

midplane policy init --url $DATABASE_URL -o policy.yaml   # scaffold a commented file
midplane policy validate policy.yaml                      # check against the server's schema
midplane policy lint policy.yaml                          # surface risky postures
midplane policy test policy.yaml --sql "DELETE FROM users WHERE id = 1"   # dry-run a query

At an interactive terminal, midplane init is the friendlier path — the same scaffold generator with a per-table wizard that validates and lints before writing. midplane policy init is the flag-driven form for scripts and CI.

`policy init`

Scaffold a commented policy file. With --url, connect read-only, list every table in the public schema, and emit each under table_access with default: read. The DSN is never printed or written into the scaffold.

Flag	Purpose
`--url <dsn>`	Connect and scaffold from `public` tables. Omit for a static starter template.
`-o`, `--out <file>`	Write to a file instead of stdout. Refuses to overwrite an existing file.

# Scaffold from a live DB. DATABASE_URL must expand INSIDE the container.
docker exec midplane sh -lc 'midplane policy init --url "$DATABASE_URL"' > policy.yaml

Exit codes: 0 on success; 1 if the output file already exists or the introspection connection fails.

`policy validate`

Validate a file against the server’s schema plus the loader’s semantic rules (mappings / overrides conflict, reserved or duplicate database names, the name regex). Prints OK, or INVALID followed by each error as path: message.

midplane policy validate policy.yaml

Synopsis: midplane policy validate <file> Exit codes: 0 when valid (OK); 1 when invalid; 2 on a usage error (no <file>).

`policy lint`

Report security-posture findings the schema can’t see. Findings are graded:

Severity	Example	Exit
`[ERROR]`	`default: read_write` — every unlisted table is writable, including tables added later.	nonzero
`[WARN]`	A guardrail explicitly disabled (`block_ddl: false` or `block_unqualified_dml: false`) widens what a `read_write` table can do.	`0`
`[INFO]`	Lists which tables were granted `read_write`, so you can confirm each is intentional.	`0`

midplane policy lint policy.yaml

Lint exits nonzero only on an error-level finding, which makes it a good CI gate — wire it in so a default: read_write can’t merge. Synopsis: midplane policy lint <file> Exit codes: 0 when there are no error-level findings (warnings and info still exit 0); 1 on any [ERROR] finding; 2 if the file isn’t schema-valid (run validate first) or <file> is missing.

`policy test`

Evaluate a query and print ALLOW or DENY, the deciding rule, and the exact agent-facing denial message. Pass exactly one of <file> (offline, no database connection) or --server (the /admin/dry-run endpoint of a running server’s currently-loaded policy, which also prints the server’s policy_hash).

Flag	Purpose
`--sql "<query>"`	The query to evaluate. Required.
`--server [url]`	Test the running server’s loaded policy via `/admin/dry-run`. Defaults to `http://localhost:$PORT`.
`--token <token>`	The server’s `INDEXER_TOKEN`. Required by `--server`, or set `INDEXER_TOKEN` in the env.
`--db <name>`	Which `databases[]` entry to test. Defaults to the first; warns if you don’t pick when more than one is configured.
`--json`	Emit the verdict as JSON.

# Against a file:
midplane policy test policy.yaml \
  --sql "DELETE FROM users"

# Against the running server:
docker exec midplane midplane policy test --server \
  --sql "DROP TABLE orders" --token "$INDEXER_TOKEN"

An ALLOW prints the statement and that it would reach the database; a DENY prints the deciding rule and the exact agent-facing message:

DENY
  database:  __default__ (postgres)
  rule:      table_access
  message:   ...
  → blocked; the query never reaches the database

Synopsis: midplane policy test (<file> | --server [url]) --sql "<query>" [--token <token>] [--db <name>] [--json] Exit codes: 0 on ALLOW; 1 on DENY (or a load error); 2 on a usage error (missing --sql, both/neither of <file>/--server, or an unknown --db).

`policy help`

midplane policy help     # also: midplane policy --help, -h, or no subcommand

`midplane audit`

Read the local SQLite audit log. All five subcommands are read-only against DB_PATH (default /data/audit.db) and open SQLite directly, so they don’t need INDEXER_TOKEN. See reading the audit log.

`audit tail`

Stream audit events as JSON lines: backfill recent rows, then poll for new ones (Ctrl-C to stop).

Flag	Default	Purpose
`--backfill <N>`	`10`	Number of recent rows to emit before following.
`--no-follow`	—	Emit the backfill and exit instead of polling.

docker exec midplane midplane audit tail --backfill 50 \
  | jq 'select(.event_type == "DECIDED" and .payload.decision == "DENY")'

Synopsis: midplane audit tail [--backfill N] [--no-follow]

`audit since`

Dump every event whose timestamp falls within a duration window. Durations are sums of N + s|m|h|d tokens: 1h, 30m, 7d, 1d12h.

docker exec midplane midplane audit since 1h

Synopsis: midplane audit since <duration> Exit codes: 2 on a missing or malformed duration.

`audit denies`

Show what got blocked and why. Joins each DENY decision to its ATTEMPTED row, printing the blocked SQL, the deciding rule, the agent-facing reason, and the agent’s stated intent together. Truncation is announced, never silent.

Flag	Default	Purpose
`--since <duration>`	(all)	Only denials within this window (`1h`, `7d`, …).
`--limit <N>`	—	Cap the number of denials shown (the latest).

docker exec midplane midplane audit denies --since 24h

Synopsis: midplane audit denies [--since DURATION] [--limit N]

`audit show`

Show every event for one query: agent, intent, full SQL, and the ATTEMPTED → DECIDED → EXECUTED/FAILED chain. Takes the qid=… that tail / denies print (an individual event id also works).

docker exec midplane midplane audit show 01HXXX...

Synopsis: midplane audit show <query_id> Exit codes: 2 on a missing <query_id>; 1 if no event matches it.

`audit stats`

Group-by summary over a window: event types, top deny rules, top allow statement types, and top agents.

Flag	Default	Purpose
`--since <duration>`	`24h`	The window to summarize.
`--json`	—	Emit the summary as JSON instead of tables.

docker exec midplane midplane audit stats --since 7d --json

Synopsis: midplane audit stats [--since DURATION] [--json] Exit codes: 2 on a malformed --since duration.

`audit help`

midplane audit help      # also: midplane audit --help, -h, or no subcommand

`midplane version` and `midplane help`

midplane version    # print the engine version
midplane help       # top-level usage

Common exit codes

Code	Meaning
`0`	Success (and `ALLOW` / `OK` for `policy test` / `policy validate`).
`1`	A failure: `DENY`, `INVALID`, a lint `[ERROR]`, or an I/O / connection error.
`2`	A usage error: an unknown subcommand, a missing required argument, or a malformed flag value.

Policy file schema

What policy init / validate / lint operate on.

Audit events

The rows audit tail / since / stats read.

Configuration

Protocol & data

`midplane server`

`midplane init`

`midplane query`

`midplane doctor`

`midplane policy`

`policy init`

`policy validate`

`policy lint`

`policy test`

`policy help`

`midplane audit`

`audit tail`

`audit since`

`audit denies`

`audit show`

`audit stats`

`audit help`

`midplane version` and `midplane help`

Common exit codes

Policy file schema

Audit events

​midplane server

​midplane init

​midplane query

​midplane doctor

​midplane policy

​policy init

​policy validate

​policy lint

​policy test

​policy help

​midplane audit

​audit tail

​audit since

​audit denies

​audit show

​audit stats

​audit help

​midplane version and midplane help

​Common exit codes

​Related

Policy file schema

Audit events

`midplane server`

`midplane init`

`midplane query`

`midplane doctor`

`midplane policy`

`policy init`

`policy validate`

`policy lint`

`policy test`

`policy help`

`midplane audit`

`audit tail`

`audit since`

`audit denies`

`audit show`

`audit stats`

`audit help`

`midplane version` and `midplane help`

Common exit codes

Related