# afpsql CLI reference
<!-- Generated by `afpsql --docs`. Do not edit by hand. -->
A PostgreSQL interface for AI agents: reliable, structured, explicit, and read-only by default.
`afpsql` is compiled from a closed `cli-spec-v1` registry: one source for argv parsing, typed invocation values, which parameter combinations are legal, output contracts, and help. An invocation runs only when it matches exactly one registered combination.
## Global arguments
AFDATA registers these itself, so the syntax in [Commands](#commands) leaves them out.
| Argument | Where | What it does |
|---|---|---|
| `--help` | every command | Every legal shape of that command, complete, plus its subcommands. JSON by default; `--output plain` for a terminal. |
| `--version` | afpsql only | Name, version, and build identity as one protocol result. |
| `--docs` | afpsql only | This document, rendered from the registry. |
| `--output <FORMAT>` | per output contract | Render as json, yaml, plain (default `json`). |
| `--output-to <DESTINATION>` | per output contract | Route results and diagnostics to split, stdout, stderr (default `split`). |
| `--stdout-file <PATH>`, `--stderr-file <PATH>` | per output contract | Append that stream to a file instead. |
Success output is protocol events, on those terms, unless a command's own **Output** line says otherwise.
A **shape** is one legal set of arguments that may appear together, under a stable id. Where a command has more than one, each id is a heading below. `--help` returns them all at once, so discovering a command costs one call; there is no recursive mode across commands, and this document is that view.
## Commands
- [`afpsql`](#afpsql) — Run one SQL action per process, or open a long-lived pipe session.
- [`afpsql inspect database`](#afpsql-inspect-database) — Summarize the connected database: schema/table/view/sequence counts and size.
- [`afpsql inspect databases`](#afpsql-inspect-databases) — List databases on the connected server with size, encoding, and connection facts.
- [`afpsql inspect indexes`](#afpsql-inspect-indexes) — List indexes with definitions, size, validity, and optional usage stats.
- [`afpsql inspect schema`](#afpsql-inspect-schema) — Export full schema metadata for one schema.
- [`afpsql inspect schemas`](#afpsql-inspect-schemas) — List user-visible schemas with owner, object counts, and size.
- [`afpsql inspect snapshot`](#afpsql-inspect-snapshot) — Export a stable full-schema snapshot for machine consumption.
- [`afpsql inspect table`](#afpsql-inspect-table) — Describe a table's columns: types, nullability, defaults, primary key, comments.
- [`afpsql inspect tables`](#afpsql-inspect-tables) — List tables in a schema with owner, estimated rows, and size.
- [`afpsql inspect views`](#afpsql-inspect-views) — List views (regular and materialized) in a schema with owner.
- [`afpsql psql install`](#afpsql-psql-install) — Install an afpsql-managed psql wrapper.
- [`afpsql psql status`](#afpsql-psql-status) — Show whether the afpsql-managed psql wrapper is installed and active.
- [`afpsql psql uninstall`](#afpsql-psql-uninstall) — Remove an afpsql-managed psql wrapper.
- [`afpsql skill install`](#afpsql-skill-install) — Install the Agent-First PSQL skill.
- [`afpsql skill status`](#afpsql-skill-status) — Show whether the Agent-First PSQL skill is installed, valid, and up to date.
- [`afpsql skill uninstall`](#afpsql-skill-uninstall) — Remove an afpsql-managed Agent-First PSQL skill.
### `afpsql`
Run one SQL action per process, or open a long-lived pipe session.
#### `query-inline` — Run inline --sql and return one bounded result
```
afpsql --sql <SQL> [--param <N=VALUE>...] [--statement-timeout-ms <MS>] [--lock-timeout-ms <MS>] [--inline-max-rows <N>] [--inline-max-bytes <N>] [--permission <read|write|ssh-read|ssh-write|container-read|container-write>] [--dry-run] [--explain <plan|analyze>] [--mode cli] [--dsn <SOURCE>] [--conninfo <SOURCE>] [--host <HOST>] [--port <PORT>] [--user <USER>] [--dbname <DBNAME>] [--password <SOURCE>] [--ssh <USER@HOST>] [--ssh-via <USER@HOST>...] [--ssh-option <OPTION>...] [--ssh-remote-socket <PATH>] [--ssh-sudo-user <USER>] [--container-docker-name <NAME>] [--container-docker-user <USER>] [--container-docker-context <CONTEXT>] [--container-docker-runtime <COMMAND>] [--container-podman-name <NAME>] [--container-podman-user <USER>] [--container-podman-runtime <COMMAND>] [--container-nerdctl-name <NAME>] [--container-nerdctl-user <USER>] [--container-nerdctl-runtime <COMMAND>] [--container-compose-service <NAME>] [--container-compose-user <USER>] [--container-compose-file <FILE>...] [--container-compose-project <NAME>] [--container-compose-runtime <COMMAND>] [--container-kubectl-pod <NAME>] [--container-kubectl-container <NAME>] [--container-kubectl-namespace <NAMESPACE>] [--container-kubectl-context <CONTEXT>] [--container-kubectl-runtime <COMMAND>] [--log <FILTER>...]
```
#### `query-file` — Run SQL read from --sql-file and return one bounded result
```
afpsql --sql-file <PATH> [--param <N=VALUE>...] [--statement-timeout-ms <MS>] [--lock-timeout-ms <MS>] [--inline-max-rows <N>] [--inline-max-bytes <N>] [--permission <read|write|ssh-read|ssh-write|container-read|container-write>] [--dry-run] [--explain <plan|analyze>] [--mode cli] [--dsn <SOURCE>] [--conninfo <SOURCE>] [--host <HOST>] [--port <PORT>] [--user <USER>] [--dbname <DBNAME>] [--password <SOURCE>] [--ssh <USER@HOST>] [--ssh-via <USER@HOST>...] [--ssh-option <OPTION>...] [--ssh-remote-socket <PATH>] [--ssh-sudo-user <USER>] [--container-docker-name <NAME>] [--container-docker-user <USER>] [--container-docker-context <CONTEXT>] [--container-docker-runtime <COMMAND>] [--container-podman-name <NAME>] [--container-podman-user <USER>] [--container-podman-runtime <COMMAND>] [--container-nerdctl-name <NAME>] [--container-nerdctl-user <USER>] [--container-nerdctl-runtime <COMMAND>] [--container-compose-service <NAME>] [--container-compose-user <USER>] [--container-compose-file <FILE>...] [--container-compose-project <NAME>] [--container-compose-runtime <COMMAND>] [--container-kubectl-pod <NAME>] [--container-kubectl-container <NAME>] [--container-kubectl-namespace <NAMESPACE>] [--container-kubectl-context <CONTEXT>] [--container-kubectl-runtime <COMMAND>] [--log <FILTER>...]
```
#### `query-inline-stream` — Stream inline --sql as ordered row batches on one stream
```
afpsql --sql <SQL> [--param <N=VALUE>...] --stream-rows [--batch-rows <N>] [--batch-bytes <N>] [--statement-timeout-ms <MS>] [--lock-timeout-ms <MS>] [--permission <read|write|ssh-read|ssh-write|container-read|container-write>] [--explain <plan|analyze>] [--mode cli] [--dsn <SOURCE>] [--conninfo <SOURCE>] [--host <HOST>] [--port <PORT>] [--user <USER>] [--dbname <DBNAME>] [--password <SOURCE>] [--ssh <USER@HOST>] [--ssh-via <USER@HOST>...] [--ssh-option <OPTION>...] [--ssh-remote-socket <PATH>] [--ssh-sudo-user <USER>] [--container-docker-name <NAME>] [--container-docker-user <USER>] [--container-docker-context <CONTEXT>] [--container-docker-runtime <COMMAND>] [--container-podman-name <NAME>] [--container-podman-user <USER>] [--container-podman-runtime <COMMAND>] [--container-nerdctl-name <NAME>] [--container-nerdctl-user <USER>] [--container-nerdctl-runtime <COMMAND>] [--container-compose-service <NAME>] [--container-compose-user <USER>] [--container-compose-file <FILE>...] [--container-compose-project <NAME>] [--container-compose-runtime <COMMAND>] [--container-kubectl-pod <NAME>] [--container-kubectl-container <NAME>] [--container-kubectl-namespace <NAMESPACE>] [--container-kubectl-context <CONTEXT>] [--container-kubectl-runtime <COMMAND>] [--log <FILTER>...]
```
#### `query-file-stream` — Stream SQL read from --sql-file as ordered row batches on one stream
```
afpsql --sql-file <PATH> [--param <N=VALUE>...] --stream-rows [--batch-rows <N>] [--batch-bytes <N>] [--statement-timeout-ms <MS>] [--lock-timeout-ms <MS>] [--permission <read|write|ssh-read|ssh-write|container-read|container-write>] [--explain <plan|analyze>] [--mode cli] [--dsn <SOURCE>] [--conninfo <SOURCE>] [--host <HOST>] [--port <PORT>] [--user <USER>] [--dbname <DBNAME>] [--password <SOURCE>] [--ssh <USER@HOST>] [--ssh-via <USER@HOST>...] [--ssh-option <OPTION>...] [--ssh-remote-socket <PATH>] [--ssh-sudo-user <USER>] [--container-docker-name <NAME>] [--container-docker-user <USER>] [--container-docker-context <CONTEXT>] [--container-docker-runtime <COMMAND>] [--container-podman-name <NAME>] [--container-podman-user <USER>] [--container-podman-runtime <COMMAND>] [--container-nerdctl-name <NAME>] [--container-nerdctl-user <USER>] [--container-nerdctl-runtime <COMMAND>] [--container-compose-service <NAME>] [--container-compose-user <USER>] [--container-compose-file <FILE>...] [--container-compose-project <NAME>] [--container-compose-runtime <COMMAND>] [--container-kubectl-pod <NAME>] [--container-kubectl-container <NAME>] [--container-kubectl-namespace <NAMESPACE>] [--container-kubectl-context <CONTEXT>] [--container-kubectl-runtime <COMMAND>] [--log <FILTER>...]
```
#### `pipe` — Open a long-lived JSONL session that reads requests from stdin
```
afpsql --mode pipe [--dsn <SOURCE>] [--conninfo <SOURCE>] [--host <HOST>] [--port <PORT>] [--user <USER>] [--dbname <DBNAME>] [--password <SOURCE>] [--ssh <USER@HOST>] [--ssh-via <USER@HOST>...] [--ssh-option <OPTION>...] [--ssh-remote-socket <PATH>] [--ssh-sudo-user <USER>] [--container-docker-name <NAME>] [--container-docker-user <USER>] [--container-docker-context <CONTEXT>] [--container-docker-runtime <COMMAND>] [--container-podman-name <NAME>] [--container-podman-user <USER>] [--container-podman-runtime <COMMAND>] [--container-nerdctl-name <NAME>] [--container-nerdctl-user <USER>] [--container-nerdctl-runtime <COMMAND>] [--container-compose-service <NAME>] [--container-compose-user <USER>] [--container-compose-file <FILE>...] [--container-compose-project <NAME>] [--container-compose-runtime <COMMAND>] [--container-kubectl-pod <NAME>] [--container-kubectl-container <NAME>] [--container-kubectl-namespace <NAMESPACE>] [--container-kubectl-context <CONTEXT>] [--container-kubectl-runtime <COMMAND>] [--log <FILTER>...]
```
#### `psql-translation` — Translate a psql command line: every remaining argument is psql's own (-c, -f, -l, -h, -p, -U, -d, -v, DBNAME USERNAME), parsed by the compatibility layer rather than by this registry
```
afpsql --mode psql
```
Output differs by combination:
- protocol events; `--output` json/yaml/plain (default `json`), `--output-to` split/stdout/stderr (default `split`); redirect with `--stdout-file` or `--stderr-file`
- protocol events; `--output` json/yaml/plain (default `json`), `--output-to` stdout/stderr (default `stdout`); redirect with `--stdout-file` or `--stderr-file`
Arguments across every shape above:
| Argument | Meaning |
|---|---|
| `--sql` | Inline SQL to execute |
| `--sql-file` | File to read SQL from; `-` reads it from stdin |
| `--param` | Positional bind parameter in N=value form; repeat for more parameters. Bare null/true/false bind as JSON null/booleans; prefix with `text:` to bind any value as a literal string |
| `--stream-rows` | Stream the result as ordered result_rows batches instead of one payload |
| `--batch-rows` | Maximum rows per streamed batch |
| `--batch-bytes` | Soft byte target per streamed batch |
| `--statement-timeout-ms` | Per-query statement timeout in milliseconds |
| `--lock-timeout-ms` | Per-query lock timeout in milliseconds |
| `--inline-max-rows` | Maximum inline rows before returning a truncated result |
| `--inline-max-bytes` | Maximum inline payload bytes before returning a truncated result |
| `--permission` | Query permission policy; defaults to read, ssh-read with --ssh, or container-read with a --container-<driver>-* flag |
| `--dry-run` | Prepare the query and report its shape without running it |
| `--explain` | Return the plan instead of the rows: `plan` wraps the SQL in EXPLAIN (FORMAT JSON); `analyze` runs it and buffers metrics |
| `--mode` | Runtime mode: one SQL action, a long-lived JSONL session, or psql argument translation |
| `--dsn` | PostgreSQL DSN source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--conninfo` | libpq conninfo source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--host` | PostgreSQL host |
| `--port` | PostgreSQL port |
| `--user` | PostgreSQL user name |
| `--dbname` | PostgreSQL database name |
| `--password` | PostgreSQL password source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--ssh` | Open an SSH transport to USER@HOST before connecting to PostgreSQL |
| `--ssh-via` | SSH hop to reach before the final --ssh destination; repeat for more hops |
| `--ssh-option` | Additional OpenSSH -o option; repeat for more options |
| `--ssh-remote-socket` | Explicit remote PostgreSQL Unix socket path for SSH forwarding |
| `--ssh-sudo-user` | Remote OS user for the sudo -n Unix-socket bridge; needs an explicit socket |
| `--container-docker-name` | Run a docker exec stdio bridge in this container before connecting |
| `--container-docker-user` | Container OS user to run the docker exec bridge as |
| `--container-docker-context` | Docker context to run the exec against |
| `--container-docker-runtime` | Docker runtime command; defaults to docker |
| `--container-podman-name` | Run a podman exec stdio bridge in this container before connecting |
| `--container-podman-user` | Container OS user to run the podman exec bridge as |
| `--container-podman-runtime` | Podman runtime command; defaults to podman |
| `--container-nerdctl-name` | Run a nerdctl exec stdio bridge in this container before connecting |
| `--container-nerdctl-user` | Container OS user to run the nerdctl exec bridge as |
| `--container-nerdctl-runtime` | Nerdctl runtime command; defaults to nerdctl |
| `--container-compose-service` | Run a compose exec stdio bridge in this service before connecting |
| `--container-compose-user` | Container OS user to run the compose exec bridge as |
| `--container-compose-file` | Compose file passed before compose exec; repeat for more files |
| `--container-compose-project` | Compose project name passed before compose exec |
| `--container-compose-runtime` | Compose runtime command; defaults to docker, use docker-compose for v1 |
| `--container-kubectl-pod` | Run a kubectl exec stdio bridge in this pod before connecting |
| `--container-kubectl-container` | Container within a multi-container pod to exec into |
| `--container-kubectl-namespace` | Kubernetes namespace to run the exec in |
| `--container-kubectl-context` | Kubernetes context to run the exec against |
| `--container-kubectl-runtime` | Kubectl runtime command; defaults to kubectl |
| `--log` | Diagnostic log filter: startup, connect, query, transport, mode, an exact event such as query.error, or all. Comma-separated or repeated |
### `afpsql inspect database`
Summarize the connected database: schema/table/view/sequence counts and size.
```
afpsql inspect database [--dsn <SOURCE>] [--conninfo <SOURCE>] [--host <HOST>] [--port <PORT>] [--user <USER>] [--dbname <DBNAME>] [--password <SOURCE>] [--ssh <USER@HOST>] [--ssh-via <USER@HOST>...] [--ssh-option <OPTION>...] [--ssh-remote-socket <PATH>] [--ssh-sudo-user <USER>] [--container-docker-name <NAME>] [--container-docker-user <USER>] [--container-docker-context <CONTEXT>] [--container-docker-runtime <COMMAND>] [--container-podman-name <NAME>] [--container-podman-user <USER>] [--container-podman-runtime <COMMAND>] [--container-nerdctl-name <NAME>] [--container-nerdctl-user <USER>] [--container-nerdctl-runtime <COMMAND>] [--container-compose-service <NAME>] [--container-compose-user <USER>] [--container-compose-file <FILE>...] [--container-compose-project <NAME>] [--container-compose-runtime <COMMAND>] [--container-kubectl-pod <NAME>] [--container-kubectl-container <NAME>] [--container-kubectl-namespace <NAMESPACE>] [--container-kubectl-context <CONTEXT>] [--container-kubectl-runtime <COMMAND>] [--log <FILTER>...]
```
| Argument | Meaning |
|---|---|
| `--dsn` | PostgreSQL DSN source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--conninfo` | libpq conninfo source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--host` | PostgreSQL host |
| `--port` | PostgreSQL port |
| `--user` | PostgreSQL user name |
| `--dbname` | PostgreSQL database name |
| `--password` | PostgreSQL password source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--ssh` | Open an SSH transport to USER@HOST before connecting to PostgreSQL |
| `--ssh-via` | SSH hop to reach before the final --ssh destination; repeat for more hops |
| `--ssh-option` | Additional OpenSSH -o option; repeat for more options |
| `--ssh-remote-socket` | Explicit remote PostgreSQL Unix socket path for SSH forwarding |
| `--ssh-sudo-user` | Remote OS user for the sudo -n Unix-socket bridge; needs an explicit socket |
| `--container-docker-name` | Run a docker exec stdio bridge in this container before connecting |
| `--container-docker-user` | Container OS user to run the docker exec bridge as |
| `--container-docker-context` | Docker context to run the exec against |
| `--container-docker-runtime` | Docker runtime command; defaults to docker |
| `--container-podman-name` | Run a podman exec stdio bridge in this container before connecting |
| `--container-podman-user` | Container OS user to run the podman exec bridge as |
| `--container-podman-runtime` | Podman runtime command; defaults to podman |
| `--container-nerdctl-name` | Run a nerdctl exec stdio bridge in this container before connecting |
| `--container-nerdctl-user` | Container OS user to run the nerdctl exec bridge as |
| `--container-nerdctl-runtime` | Nerdctl runtime command; defaults to nerdctl |
| `--container-compose-service` | Run a compose exec stdio bridge in this service before connecting |
| `--container-compose-user` | Container OS user to run the compose exec bridge as |
| `--container-compose-file` | Compose file passed before compose exec; repeat for more files |
| `--container-compose-project` | Compose project name passed before compose exec |
| `--container-compose-runtime` | Compose runtime command; defaults to docker, use docker-compose for v1 |
| `--container-kubectl-pod` | Run a kubectl exec stdio bridge in this pod before connecting |
| `--container-kubectl-container` | Container within a multi-container pod to exec into |
| `--container-kubectl-namespace` | Kubernetes namespace to run the exec in |
| `--container-kubectl-context` | Kubernetes context to run the exec against |
| `--container-kubectl-runtime` | Kubectl runtime command; defaults to kubectl |
| `--log` | Diagnostic log filter: startup, connect, query, transport, mode, an exact event such as query.error, or all. Comma-separated or repeated |
### `afpsql inspect databases`
List databases on the connected server with size, encoding, and connection facts.
```
afpsql inspect databases [--dsn <SOURCE>] [--conninfo <SOURCE>] [--host <HOST>] [--port <PORT>] [--user <USER>] [--dbname <DBNAME>] [--password <SOURCE>] [--ssh <USER@HOST>] [--ssh-via <USER@HOST>...] [--ssh-option <OPTION>...] [--ssh-remote-socket <PATH>] [--ssh-sudo-user <USER>] [--container-docker-name <NAME>] [--container-docker-user <USER>] [--container-docker-context <CONTEXT>] [--container-docker-runtime <COMMAND>] [--container-podman-name <NAME>] [--container-podman-user <USER>] [--container-podman-runtime <COMMAND>] [--container-nerdctl-name <NAME>] [--container-nerdctl-user <USER>] [--container-nerdctl-runtime <COMMAND>] [--container-compose-service <NAME>] [--container-compose-user <USER>] [--container-compose-file <FILE>...] [--container-compose-project <NAME>] [--container-compose-runtime <COMMAND>] [--container-kubectl-pod <NAME>] [--container-kubectl-container <NAME>] [--container-kubectl-namespace <NAMESPACE>] [--container-kubectl-context <CONTEXT>] [--container-kubectl-runtime <COMMAND>] [--log <FILTER>...] [--all]
```
| Argument | Meaning |
|---|---|
| `--dsn` | PostgreSQL DSN source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--conninfo` | libpq conninfo source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--host` | PostgreSQL host |
| `--port` | PostgreSQL port |
| `--user` | PostgreSQL user name |
| `--dbname` | PostgreSQL database name |
| `--password` | PostgreSQL password source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--ssh` | Open an SSH transport to USER@HOST before connecting to PostgreSQL |
| `--ssh-via` | SSH hop to reach before the final --ssh destination; repeat for more hops |
| `--ssh-option` | Additional OpenSSH -o option; repeat for more options |
| `--ssh-remote-socket` | Explicit remote PostgreSQL Unix socket path for SSH forwarding |
| `--ssh-sudo-user` | Remote OS user for the sudo -n Unix-socket bridge; needs an explicit socket |
| `--container-docker-name` | Run a docker exec stdio bridge in this container before connecting |
| `--container-docker-user` | Container OS user to run the docker exec bridge as |
| `--container-docker-context` | Docker context to run the exec against |
| `--container-docker-runtime` | Docker runtime command; defaults to docker |
| `--container-podman-name` | Run a podman exec stdio bridge in this container before connecting |
| `--container-podman-user` | Container OS user to run the podman exec bridge as |
| `--container-podman-runtime` | Podman runtime command; defaults to podman |
| `--container-nerdctl-name` | Run a nerdctl exec stdio bridge in this container before connecting |
| `--container-nerdctl-user` | Container OS user to run the nerdctl exec bridge as |
| `--container-nerdctl-runtime` | Nerdctl runtime command; defaults to nerdctl |
| `--container-compose-service` | Run a compose exec stdio bridge in this service before connecting |
| `--container-compose-user` | Container OS user to run the compose exec bridge as |
| `--container-compose-file` | Compose file passed before compose exec; repeat for more files |
| `--container-compose-project` | Compose project name passed before compose exec |
| `--container-compose-runtime` | Compose runtime command; defaults to docker, use docker-compose for v1 |
| `--container-kubectl-pod` | Run a kubectl exec stdio bridge in this pod before connecting |
| `--container-kubectl-container` | Container within a multi-container pod to exec into |
| `--container-kubectl-namespace` | Kubernetes namespace to run the exec in |
| `--container-kubectl-context` | Kubernetes context to run the exec against |
| `--container-kubectl-runtime` | Kubectl runtime command; defaults to kubectl |
| `--log` | Diagnostic log filter: startup, connect, query, transport, mode, an exact event such as query.error, or all. Comma-separated or repeated |
| `--all` | Include template databases (template0/template1) |
### `afpsql inspect indexes`
List indexes with definitions, size, validity, and optional usage stats.
```
afpsql inspect indexes [--dsn <SOURCE>] [--conninfo <SOURCE>] [--host <HOST>] [--port <PORT>] [--user <USER>] [--dbname <DBNAME>] [--password <SOURCE>] [--ssh <USER@HOST>] [--ssh-via <USER@HOST>...] [--ssh-option <OPTION>...] [--ssh-remote-socket <PATH>] [--ssh-sudo-user <USER>] [--container-docker-name <NAME>] [--container-docker-user <USER>] [--container-docker-context <CONTEXT>] [--container-docker-runtime <COMMAND>] [--container-podman-name <NAME>] [--container-podman-user <USER>] [--container-podman-runtime <COMMAND>] [--container-nerdctl-name <NAME>] [--container-nerdctl-user <USER>] [--container-nerdctl-runtime <COMMAND>] [--container-compose-service <NAME>] [--container-compose-user <USER>] [--container-compose-file <FILE>...] [--container-compose-project <NAME>] [--container-compose-runtime <COMMAND>] [--container-kubectl-pod <NAME>] [--container-kubectl-container <NAME>] [--container-kubectl-namespace <NAMESPACE>] [--container-kubectl-context <CONTEXT>] [--container-kubectl-runtime <COMMAND>] [--log <FILTER>...] [--schema <SCHEMA>] [--table <TABLE>] [--stats]
```
| Argument | Meaning |
|---|---|
| `--dsn` | PostgreSQL DSN source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--conninfo` | libpq conninfo source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--host` | PostgreSQL host |
| `--port` | PostgreSQL port |
| `--user` | PostgreSQL user name |
| `--dbname` | PostgreSQL database name |
| `--password` | PostgreSQL password source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--ssh` | Open an SSH transport to USER@HOST before connecting to PostgreSQL |
| `--ssh-via` | SSH hop to reach before the final --ssh destination; repeat for more hops |
| `--ssh-option` | Additional OpenSSH -o option; repeat for more options |
| `--ssh-remote-socket` | Explicit remote PostgreSQL Unix socket path for SSH forwarding |
| `--ssh-sudo-user` | Remote OS user for the sudo -n Unix-socket bridge; needs an explicit socket |
| `--container-docker-name` | Run a docker exec stdio bridge in this container before connecting |
| `--container-docker-user` | Container OS user to run the docker exec bridge as |
| `--container-docker-context` | Docker context to run the exec against |
| `--container-docker-runtime` | Docker runtime command; defaults to docker |
| `--container-podman-name` | Run a podman exec stdio bridge in this container before connecting |
| `--container-podman-user` | Container OS user to run the podman exec bridge as |
| `--container-podman-runtime` | Podman runtime command; defaults to podman |
| `--container-nerdctl-name` | Run a nerdctl exec stdio bridge in this container before connecting |
| `--container-nerdctl-user` | Container OS user to run the nerdctl exec bridge as |
| `--container-nerdctl-runtime` | Nerdctl runtime command; defaults to nerdctl |
| `--container-compose-service` | Run a compose exec stdio bridge in this service before connecting |
| `--container-compose-user` | Container OS user to run the compose exec bridge as |
| `--container-compose-file` | Compose file passed before compose exec; repeat for more files |
| `--container-compose-project` | Compose project name passed before compose exec |
| `--container-compose-runtime` | Compose runtime command; defaults to docker, use docker-compose for v1 |
| `--container-kubectl-pod` | Run a kubectl exec stdio bridge in this pod before connecting |
| `--container-kubectl-container` | Container within a multi-container pod to exec into |
| `--container-kubectl-namespace` | Kubernetes namespace to run the exec in |
| `--container-kubectl-context` | Kubernetes context to run the exec against |
| `--container-kubectl-runtime` | Kubectl runtime command; defaults to kubectl |
| `--log` | Diagnostic log filter: startup, connect, query, transport, mode, an exact event such as query.error, or all. Comma-separated or repeated |
| `--schema` | Schema to filter on |
| `--table` | Table to filter on; `schema.table` overrides --schema |
| `--stats` | Include PostgreSQL's built-in pg_stat_user_indexes usage counters |
### `afpsql inspect schema`
Export full schema metadata for one schema.
```
afpsql inspect schema [--dsn <SOURCE>] [--conninfo <SOURCE>] [--host <HOST>] [--port <PORT>] [--user <USER>] [--dbname <DBNAME>] [--password <SOURCE>] [--ssh <USER@HOST>] [--ssh-via <USER@HOST>...] [--ssh-option <OPTION>...] [--ssh-remote-socket <PATH>] [--ssh-sudo-user <USER>] [--container-docker-name <NAME>] [--container-docker-user <USER>] [--container-docker-context <CONTEXT>] [--container-docker-runtime <COMMAND>] [--container-podman-name <NAME>] [--container-podman-user <USER>] [--container-podman-runtime <COMMAND>] [--container-nerdctl-name <NAME>] [--container-nerdctl-user <USER>] [--container-nerdctl-runtime <COMMAND>] [--container-compose-service <NAME>] [--container-compose-user <USER>] [--container-compose-file <FILE>...] [--container-compose-project <NAME>] [--container-compose-runtime <COMMAND>] [--container-kubectl-pod <NAME>] [--container-kubectl-container <NAME>] [--container-kubectl-namespace <NAMESPACE>] [--container-kubectl-context <CONTEXT>] [--container-kubectl-runtime <COMMAND>] [--log <FILTER>...] [--schema <SCHEMA>] [--like <PATTERN>]
```
| Argument | Meaning |
|---|---|
| `--dsn` | PostgreSQL DSN source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--conninfo` | libpq conninfo source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--host` | PostgreSQL host |
| `--port` | PostgreSQL port |
| `--user` | PostgreSQL user name |
| `--dbname` | PostgreSQL database name |
| `--password` | PostgreSQL password source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--ssh` | Open an SSH transport to USER@HOST before connecting to PostgreSQL |
| `--ssh-via` | SSH hop to reach before the final --ssh destination; repeat for more hops |
| `--ssh-option` | Additional OpenSSH -o option; repeat for more options |
| `--ssh-remote-socket` | Explicit remote PostgreSQL Unix socket path for SSH forwarding |
| `--ssh-sudo-user` | Remote OS user for the sudo -n Unix-socket bridge; needs an explicit socket |
| `--container-docker-name` | Run a docker exec stdio bridge in this container before connecting |
| `--container-docker-user` | Container OS user to run the docker exec bridge as |
| `--container-docker-context` | Docker context to run the exec against |
| `--container-docker-runtime` | Docker runtime command; defaults to docker |
| `--container-podman-name` | Run a podman exec stdio bridge in this container before connecting |
| `--container-podman-user` | Container OS user to run the podman exec bridge as |
| `--container-podman-runtime` | Podman runtime command; defaults to podman |
| `--container-nerdctl-name` | Run a nerdctl exec stdio bridge in this container before connecting |
| `--container-nerdctl-user` | Container OS user to run the nerdctl exec bridge as |
| `--container-nerdctl-runtime` | Nerdctl runtime command; defaults to nerdctl |
| `--container-compose-service` | Run a compose exec stdio bridge in this service before connecting |
| `--container-compose-user` | Container OS user to run the compose exec bridge as |
| `--container-compose-file` | Compose file passed before compose exec; repeat for more files |
| `--container-compose-project` | Compose project name passed before compose exec |
| `--container-compose-runtime` | Compose runtime command; defaults to docker, use docker-compose for v1 |
| `--container-kubectl-pod` | Run a kubectl exec stdio bridge in this pod before connecting |
| `--container-kubectl-container` | Container within a multi-container pod to exec into |
| `--container-kubectl-namespace` | Kubernetes namespace to run the exec in |
| `--container-kubectl-context` | Kubernetes context to run the exec against |
| `--container-kubectl-runtime` | Kubectl runtime command; defaults to kubectl |
| `--log` | Diagnostic log filter: startup, connect, query, transport, mode, an exact event such as query.error, or all. Comma-separated or repeated |
| `--schema` | Schema to inspect |
| `--like` | Optional `LIKE` pattern matched against relation names (`%` is the wildcard) |
### `afpsql inspect schemas`
List user-visible schemas with owner, object counts, and size.
```
afpsql inspect schemas [--dsn <SOURCE>] [--conninfo <SOURCE>] [--host <HOST>] [--port <PORT>] [--user <USER>] [--dbname <DBNAME>] [--password <SOURCE>] [--ssh <USER@HOST>] [--ssh-via <USER@HOST>...] [--ssh-option <OPTION>...] [--ssh-remote-socket <PATH>] [--ssh-sudo-user <USER>] [--container-docker-name <NAME>] [--container-docker-user <USER>] [--container-docker-context <CONTEXT>] [--container-docker-runtime <COMMAND>] [--container-podman-name <NAME>] [--container-podman-user <USER>] [--container-podman-runtime <COMMAND>] [--container-nerdctl-name <NAME>] [--container-nerdctl-user <USER>] [--container-nerdctl-runtime <COMMAND>] [--container-compose-service <NAME>] [--container-compose-user <USER>] [--container-compose-file <FILE>...] [--container-compose-project <NAME>] [--container-compose-runtime <COMMAND>] [--container-kubectl-pod <NAME>] [--container-kubectl-container <NAME>] [--container-kubectl-namespace <NAMESPACE>] [--container-kubectl-context <CONTEXT>] [--container-kubectl-runtime <COMMAND>] [--log <FILTER>...]
```
| Argument | Meaning |
|---|---|
| `--dsn` | PostgreSQL DSN source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--conninfo` | libpq conninfo source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--host` | PostgreSQL host |
| `--port` | PostgreSQL port |
| `--user` | PostgreSQL user name |
| `--dbname` | PostgreSQL database name |
| `--password` | PostgreSQL password source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--ssh` | Open an SSH transport to USER@HOST before connecting to PostgreSQL |
| `--ssh-via` | SSH hop to reach before the final --ssh destination; repeat for more hops |
| `--ssh-option` | Additional OpenSSH -o option; repeat for more options |
| `--ssh-remote-socket` | Explicit remote PostgreSQL Unix socket path for SSH forwarding |
| `--ssh-sudo-user` | Remote OS user for the sudo -n Unix-socket bridge; needs an explicit socket |
| `--container-docker-name` | Run a docker exec stdio bridge in this container before connecting |
| `--container-docker-user` | Container OS user to run the docker exec bridge as |
| `--container-docker-context` | Docker context to run the exec against |
| `--container-docker-runtime` | Docker runtime command; defaults to docker |
| `--container-podman-name` | Run a podman exec stdio bridge in this container before connecting |
| `--container-podman-user` | Container OS user to run the podman exec bridge as |
| `--container-podman-runtime` | Podman runtime command; defaults to podman |
| `--container-nerdctl-name` | Run a nerdctl exec stdio bridge in this container before connecting |
| `--container-nerdctl-user` | Container OS user to run the nerdctl exec bridge as |
| `--container-nerdctl-runtime` | Nerdctl runtime command; defaults to nerdctl |
| `--container-compose-service` | Run a compose exec stdio bridge in this service before connecting |
| `--container-compose-user` | Container OS user to run the compose exec bridge as |
| `--container-compose-file` | Compose file passed before compose exec; repeat for more files |
| `--container-compose-project` | Compose project name passed before compose exec |
| `--container-compose-runtime` | Compose runtime command; defaults to docker, use docker-compose for v1 |
| `--container-kubectl-pod` | Run a kubectl exec stdio bridge in this pod before connecting |
| `--container-kubectl-container` | Container within a multi-container pod to exec into |
| `--container-kubectl-namespace` | Kubernetes namespace to run the exec in |
| `--container-kubectl-context` | Kubernetes context to run the exec against |
| `--container-kubectl-runtime` | Kubectl runtime command; defaults to kubectl |
| `--log` | Diagnostic log filter: startup, connect, query, transport, mode, an exact event such as query.error, or all. Comma-separated or repeated |
### `afpsql inspect snapshot`
Export a stable full-schema snapshot for machine consumption.
```
afpsql inspect snapshot [--dsn <SOURCE>] [--conninfo <SOURCE>] [--host <HOST>] [--port <PORT>] [--user <USER>] [--dbname <DBNAME>] [--password <SOURCE>] [--ssh <USER@HOST>] [--ssh-via <USER@HOST>...] [--ssh-option <OPTION>...] [--ssh-remote-socket <PATH>] [--ssh-sudo-user <USER>] [--container-docker-name <NAME>] [--container-docker-user <USER>] [--container-docker-context <CONTEXT>] [--container-docker-runtime <COMMAND>] [--container-podman-name <NAME>] [--container-podman-user <USER>] [--container-podman-runtime <COMMAND>] [--container-nerdctl-name <NAME>] [--container-nerdctl-user <USER>] [--container-nerdctl-runtime <COMMAND>] [--container-compose-service <NAME>] [--container-compose-user <USER>] [--container-compose-file <FILE>...] [--container-compose-project <NAME>] [--container-compose-runtime <COMMAND>] [--container-kubectl-pod <NAME>] [--container-kubectl-container <NAME>] [--container-kubectl-namespace <NAMESPACE>] [--container-kubectl-context <CONTEXT>] [--container-kubectl-runtime <COMMAND>] [--log <FILTER>...] [--schema <SCHEMA>] [--like <PATTERN>]
```
| Argument | Meaning |
|---|---|
| `--dsn` | PostgreSQL DSN source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--conninfo` | libpq conninfo source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--host` | PostgreSQL host |
| `--port` | PostgreSQL port |
| `--user` | PostgreSQL user name |
| `--dbname` | PostgreSQL database name |
| `--password` | PostgreSQL password source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--ssh` | Open an SSH transport to USER@HOST before connecting to PostgreSQL |
| `--ssh-via` | SSH hop to reach before the final --ssh destination; repeat for more hops |
| `--ssh-option` | Additional OpenSSH -o option; repeat for more options |
| `--ssh-remote-socket` | Explicit remote PostgreSQL Unix socket path for SSH forwarding |
| `--ssh-sudo-user` | Remote OS user for the sudo -n Unix-socket bridge; needs an explicit socket |
| `--container-docker-name` | Run a docker exec stdio bridge in this container before connecting |
| `--container-docker-user` | Container OS user to run the docker exec bridge as |
| `--container-docker-context` | Docker context to run the exec against |
| `--container-docker-runtime` | Docker runtime command; defaults to docker |
| `--container-podman-name` | Run a podman exec stdio bridge in this container before connecting |
| `--container-podman-user` | Container OS user to run the podman exec bridge as |
| `--container-podman-runtime` | Podman runtime command; defaults to podman |
| `--container-nerdctl-name` | Run a nerdctl exec stdio bridge in this container before connecting |
| `--container-nerdctl-user` | Container OS user to run the nerdctl exec bridge as |
| `--container-nerdctl-runtime` | Nerdctl runtime command; defaults to nerdctl |
| `--container-compose-service` | Run a compose exec stdio bridge in this service before connecting |
| `--container-compose-user` | Container OS user to run the compose exec bridge as |
| `--container-compose-file` | Compose file passed before compose exec; repeat for more files |
| `--container-compose-project` | Compose project name passed before compose exec |
| `--container-compose-runtime` | Compose runtime command; defaults to docker, use docker-compose for v1 |
| `--container-kubectl-pod` | Run a kubectl exec stdio bridge in this pod before connecting |
| `--container-kubectl-container` | Container within a multi-container pod to exec into |
| `--container-kubectl-namespace` | Kubernetes namespace to run the exec in |
| `--container-kubectl-context` | Kubernetes context to run the exec against |
| `--container-kubectl-runtime` | Kubectl runtime command; defaults to kubectl |
| `--log` | Diagnostic log filter: startup, connect, query, transport, mode, an exact event such as query.error, or all. Comma-separated or repeated |
| `--schema` | Schema to inspect |
| `--like` | Optional `LIKE` pattern matched against relation names (`%` is the wildcard) |
### `afpsql inspect table`
Describe a table's columns: types, nullability, defaults, primary key, comments.
```
afpsql inspect table <NAME> [--full] [--dsn <SOURCE>] [--conninfo <SOURCE>] [--host <HOST>] [--port <PORT>] [--user <USER>] [--dbname <DBNAME>] [--password <SOURCE>] [--ssh <USER@HOST>] [--ssh-via <USER@HOST>...] [--ssh-option <OPTION>...] [--ssh-remote-socket <PATH>] [--ssh-sudo-user <USER>] [--container-docker-name <NAME>] [--container-docker-user <USER>] [--container-docker-context <CONTEXT>] [--container-docker-runtime <COMMAND>] [--container-podman-name <NAME>] [--container-podman-user <USER>] [--container-podman-runtime <COMMAND>] [--container-nerdctl-name <NAME>] [--container-nerdctl-user <USER>] [--container-nerdctl-runtime <COMMAND>] [--container-compose-service <NAME>] [--container-compose-user <USER>] [--container-compose-file <FILE>...] [--container-compose-project <NAME>] [--container-compose-runtime <COMMAND>] [--container-kubectl-pod <NAME>] [--container-kubectl-container <NAME>] [--container-kubectl-namespace <NAMESPACE>] [--container-kubectl-context <CONTEXT>] [--container-kubectl-runtime <COMMAND>] [--log <FILTER>...]
```
| Argument | Meaning |
|---|---|
| `NAME` | Table name; `schema.table` overrides the default `public` schema |
| `--full` | Also return constraints, indexes, triggers, and sequence/default metadata |
| `--dsn` | PostgreSQL DSN source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--conninfo` | libpq conninfo source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--host` | PostgreSQL host |
| `--port` | PostgreSQL port |
| `--user` | PostgreSQL user name |
| `--dbname` | PostgreSQL database name |
| `--password` | PostgreSQL password source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--ssh` | Open an SSH transport to USER@HOST before connecting to PostgreSQL |
| `--ssh-via` | SSH hop to reach before the final --ssh destination; repeat for more hops |
| `--ssh-option` | Additional OpenSSH -o option; repeat for more options |
| `--ssh-remote-socket` | Explicit remote PostgreSQL Unix socket path for SSH forwarding |
| `--ssh-sudo-user` | Remote OS user for the sudo -n Unix-socket bridge; needs an explicit socket |
| `--container-docker-name` | Run a docker exec stdio bridge in this container before connecting |
| `--container-docker-user` | Container OS user to run the docker exec bridge as |
| `--container-docker-context` | Docker context to run the exec against |
| `--container-docker-runtime` | Docker runtime command; defaults to docker |
| `--container-podman-name` | Run a podman exec stdio bridge in this container before connecting |
| `--container-podman-user` | Container OS user to run the podman exec bridge as |
| `--container-podman-runtime` | Podman runtime command; defaults to podman |
| `--container-nerdctl-name` | Run a nerdctl exec stdio bridge in this container before connecting |
| `--container-nerdctl-user` | Container OS user to run the nerdctl exec bridge as |
| `--container-nerdctl-runtime` | Nerdctl runtime command; defaults to nerdctl |
| `--container-compose-service` | Run a compose exec stdio bridge in this service before connecting |
| `--container-compose-user` | Container OS user to run the compose exec bridge as |
| `--container-compose-file` | Compose file passed before compose exec; repeat for more files |
| `--container-compose-project` | Compose project name passed before compose exec |
| `--container-compose-runtime` | Compose runtime command; defaults to docker, use docker-compose for v1 |
| `--container-kubectl-pod` | Run a kubectl exec stdio bridge in this pod before connecting |
| `--container-kubectl-container` | Container within a multi-container pod to exec into |
| `--container-kubectl-namespace` | Kubernetes namespace to run the exec in |
| `--container-kubectl-context` | Kubernetes context to run the exec against |
| `--container-kubectl-runtime` | Kubectl runtime command; defaults to kubectl |
| `--log` | Diagnostic log filter: startup, connect, query, transport, mode, an exact event such as query.error, or all. Comma-separated or repeated |
### `afpsql inspect tables`
List tables in a schema with owner, estimated rows, and size.
```
afpsql inspect tables [--dsn <SOURCE>] [--conninfo <SOURCE>] [--host <HOST>] [--port <PORT>] [--user <USER>] [--dbname <DBNAME>] [--password <SOURCE>] [--ssh <USER@HOST>] [--ssh-via <USER@HOST>...] [--ssh-option <OPTION>...] [--ssh-remote-socket <PATH>] [--ssh-sudo-user <USER>] [--container-docker-name <NAME>] [--container-docker-user <USER>] [--container-docker-context <CONTEXT>] [--container-docker-runtime <COMMAND>] [--container-podman-name <NAME>] [--container-podman-user <USER>] [--container-podman-runtime <COMMAND>] [--container-nerdctl-name <NAME>] [--container-nerdctl-user <USER>] [--container-nerdctl-runtime <COMMAND>] [--container-compose-service <NAME>] [--container-compose-user <USER>] [--container-compose-file <FILE>...] [--container-compose-project <NAME>] [--container-compose-runtime <COMMAND>] [--container-kubectl-pod <NAME>] [--container-kubectl-container <NAME>] [--container-kubectl-namespace <NAMESPACE>] [--container-kubectl-context <CONTEXT>] [--container-kubectl-runtime <COMMAND>] [--log <FILTER>...] [--schema <SCHEMA>] [--like <PATTERN>]
```
| Argument | Meaning |
|---|---|
| `--dsn` | PostgreSQL DSN source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--conninfo` | libpq conninfo source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--host` | PostgreSQL host |
| `--port` | PostgreSQL port |
| `--user` | PostgreSQL user name |
| `--dbname` | PostgreSQL database name |
| `--password` | PostgreSQL password source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--ssh` | Open an SSH transport to USER@HOST before connecting to PostgreSQL |
| `--ssh-via` | SSH hop to reach before the final --ssh destination; repeat for more hops |
| `--ssh-option` | Additional OpenSSH -o option; repeat for more options |
| `--ssh-remote-socket` | Explicit remote PostgreSQL Unix socket path for SSH forwarding |
| `--ssh-sudo-user` | Remote OS user for the sudo -n Unix-socket bridge; needs an explicit socket |
| `--container-docker-name` | Run a docker exec stdio bridge in this container before connecting |
| `--container-docker-user` | Container OS user to run the docker exec bridge as |
| `--container-docker-context` | Docker context to run the exec against |
| `--container-docker-runtime` | Docker runtime command; defaults to docker |
| `--container-podman-name` | Run a podman exec stdio bridge in this container before connecting |
| `--container-podman-user` | Container OS user to run the podman exec bridge as |
| `--container-podman-runtime` | Podman runtime command; defaults to podman |
| `--container-nerdctl-name` | Run a nerdctl exec stdio bridge in this container before connecting |
| `--container-nerdctl-user` | Container OS user to run the nerdctl exec bridge as |
| `--container-nerdctl-runtime` | Nerdctl runtime command; defaults to nerdctl |
| `--container-compose-service` | Run a compose exec stdio bridge in this service before connecting |
| `--container-compose-user` | Container OS user to run the compose exec bridge as |
| `--container-compose-file` | Compose file passed before compose exec; repeat for more files |
| `--container-compose-project` | Compose project name passed before compose exec |
| `--container-compose-runtime` | Compose runtime command; defaults to docker, use docker-compose for v1 |
| `--container-kubectl-pod` | Run a kubectl exec stdio bridge in this pod before connecting |
| `--container-kubectl-container` | Container within a multi-container pod to exec into |
| `--container-kubectl-namespace` | Kubernetes namespace to run the exec in |
| `--container-kubectl-context` | Kubernetes context to run the exec against |
| `--container-kubectl-runtime` | Kubectl runtime command; defaults to kubectl |
| `--log` | Diagnostic log filter: startup, connect, query, transport, mode, an exact event such as query.error, or all. Comma-separated or repeated |
| `--schema` | Schema to inspect |
| `--like` | Optional `LIKE` pattern matched against the table name (`%` is the wildcard) |
### `afpsql inspect views`
List views (regular and materialized) in a schema with owner.
```
afpsql inspect views [--dsn <SOURCE>] [--conninfo <SOURCE>] [--host <HOST>] [--port <PORT>] [--user <USER>] [--dbname <DBNAME>] [--password <SOURCE>] [--ssh <USER@HOST>] [--ssh-via <USER@HOST>...] [--ssh-option <OPTION>...] [--ssh-remote-socket <PATH>] [--ssh-sudo-user <USER>] [--container-docker-name <NAME>] [--container-docker-user <USER>] [--container-docker-context <CONTEXT>] [--container-docker-runtime <COMMAND>] [--container-podman-name <NAME>] [--container-podman-user <USER>] [--container-podman-runtime <COMMAND>] [--container-nerdctl-name <NAME>] [--container-nerdctl-user <USER>] [--container-nerdctl-runtime <COMMAND>] [--container-compose-service <NAME>] [--container-compose-user <USER>] [--container-compose-file <FILE>...] [--container-compose-project <NAME>] [--container-compose-runtime <COMMAND>] [--container-kubectl-pod <NAME>] [--container-kubectl-container <NAME>] [--container-kubectl-namespace <NAMESPACE>] [--container-kubectl-context <CONTEXT>] [--container-kubectl-runtime <COMMAND>] [--log <FILTER>...] [--schema <SCHEMA>] [--like <PATTERN>]
```
| Argument | Meaning |
|---|---|
| `--dsn` | PostgreSQL DSN source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--conninfo` | libpq conninfo source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--host` | PostgreSQL host |
| `--port` | PostgreSQL port |
| `--user` | PostgreSQL user name |
| `--dbname` | PostgreSQL database name |
| `--password` | PostgreSQL password source: literal value, env:NAME, file:PATH#DOT_PATH, or literal:VALUE for a literal starting with a source prefix |
| `--ssh` | Open an SSH transport to USER@HOST before connecting to PostgreSQL |
| `--ssh-via` | SSH hop to reach before the final --ssh destination; repeat for more hops |
| `--ssh-option` | Additional OpenSSH -o option; repeat for more options |
| `--ssh-remote-socket` | Explicit remote PostgreSQL Unix socket path for SSH forwarding |
| `--ssh-sudo-user` | Remote OS user for the sudo -n Unix-socket bridge; needs an explicit socket |
| `--container-docker-name` | Run a docker exec stdio bridge in this container before connecting |
| `--container-docker-user` | Container OS user to run the docker exec bridge as |
| `--container-docker-context` | Docker context to run the exec against |
| `--container-docker-runtime` | Docker runtime command; defaults to docker |
| `--container-podman-name` | Run a podman exec stdio bridge in this container before connecting |
| `--container-podman-user` | Container OS user to run the podman exec bridge as |
| `--container-podman-runtime` | Podman runtime command; defaults to podman |
| `--container-nerdctl-name` | Run a nerdctl exec stdio bridge in this container before connecting |
| `--container-nerdctl-user` | Container OS user to run the nerdctl exec bridge as |
| `--container-nerdctl-runtime` | Nerdctl runtime command; defaults to nerdctl |
| `--container-compose-service` | Run a compose exec stdio bridge in this service before connecting |
| `--container-compose-user` | Container OS user to run the compose exec bridge as |
| `--container-compose-file` | Compose file passed before compose exec; repeat for more files |
| `--container-compose-project` | Compose project name passed before compose exec |
| `--container-compose-runtime` | Compose runtime command; defaults to docker, use docker-compose for v1 |
| `--container-kubectl-pod` | Run a kubectl exec stdio bridge in this pod before connecting |
| `--container-kubectl-container` | Container within a multi-container pod to exec into |
| `--container-kubectl-namespace` | Kubernetes namespace to run the exec in |
| `--container-kubectl-context` | Kubernetes context to run the exec against |
| `--container-kubectl-runtime` | Kubectl runtime command; defaults to kubectl |
| `--log` | Diagnostic log filter: startup, connect, query, transport, mode, an exact event such as query.error, or all. Comma-separated or repeated |
| `--schema` | Schema to inspect |
| `--like` | Optional `LIKE` pattern matched against the view name (`%` is the wildcard) |
### `afpsql psql install`
Install an afpsql-managed psql wrapper.
```
afpsql psql install [--bin-dir <DIR>]
```
| Argument | Meaning |
|---|---|
| `--bin-dir` | Directory that holds the psql wrapper; defaults to the afpsql executable directory |
### `afpsql psql status`
Show whether the afpsql-managed psql wrapper is installed and active.
```
afpsql psql status [--bin-dir <DIR>]
```
| Argument | Meaning |
|---|---|
| `--bin-dir` | Directory that holds the psql wrapper; defaults to the afpsql executable directory |
### `afpsql psql uninstall`
Remove an afpsql-managed psql wrapper.
```
afpsql psql uninstall [--bin-dir <DIR>]
```
| Argument | Meaning |
|---|---|
| `--bin-dir` | Directory that holds the psql wrapper; defaults to the afpsql executable directory |
### `afpsql skill install`
Install the Agent-First PSQL skill.
#### `skill-install-every-agent` — Target every agent that supports the scope
```
afpsql skill install [--agent all] [--scope <personal|workspace>] [--force]
```
#### `skill-install-one-agent` — Target one named agent; only this shape accepts --skills-dir
```
afpsql skill install --agent <codex|claude-code|opencode|hermes> [--scope <personal|workspace>] [--skills-dir <DIR>] [--force]
```
Arguments across every shape above:
| Argument | Meaning |
|---|---|
| `--agent` | Agent to manage |
| `--scope` | Skill scope |
| `--skills-dir` | Directory that contains skill folders |
| `--force` | Overwrite or remove an unmanaged Agent-First PSQL skill at the target path |
### `afpsql skill status`
Show whether the Agent-First PSQL skill is installed, valid, and up to date.
#### `skill-status-every-agent` — Target every agent that supports the scope
```
afpsql skill status [--agent all] [--scope <personal|workspace>]
```
#### `skill-status-one-agent` — Target one named agent; only this shape accepts --skills-dir
```
afpsql skill status --agent <codex|claude-code|opencode|hermes> [--scope <personal|workspace>] [--skills-dir <DIR>]
```
Arguments across every shape above:
| Argument | Meaning |
|---|---|
| `--agent` | Agent to manage |
| `--scope` | Skill scope |
| `--skills-dir` | Directory that contains skill folders |
### `afpsql skill uninstall`
Remove an afpsql-managed Agent-First PSQL skill.
#### `skill-uninstall-every-agent` — Target every agent that supports the scope
```
afpsql skill uninstall [--agent all] [--scope <personal|workspace>] [--force]
```
#### `skill-uninstall-one-agent` — Target one named agent; only this shape accepts --skills-dir
```
afpsql skill uninstall --agent <codex|claude-code|opencode|hermes> [--scope <personal|workspace>] [--skills-dir <DIR>] [--force]
```
Arguments across every shape above:
| Argument | Meaning |
|---|---|
| `--agent` | Agent to manage |
| `--scope` | Skill scope |
| `--skills-dir` | Directory that contains skill folders |
| `--force` | Overwrite or remove an unmanaged Agent-First PSQL skill at the target path |
## Exit codes
| Code | Meaning |
|---|---|
| 0 | The command ran and succeeded. |
| 1 | The command ran and failed. The event carries a domain `error.code`. |
| 2 | The invocation was rejected before anything ran. `error.code` is one of the `cli_*` codes below. |
| 4 | A terminal event could not be written; the requested outcome is unknown to the caller. |
The split is the useful one for a caller: exit 2 means the call was never made, so retrying it unchanged cannot help, while exit 1 means it was.
## CLI errors
Every structural failure emits one strict JSON `kind:"error"` event on stderr, leaves stdout empty, and exits 2. The `code` names the failure — `cli_unknown_argument` for an unknown spelling, `cli_unregistered_combination` for registered arguments in a mixture that is not, and one each for `cli_unknown_command`, `cli_missing_argument_value`, `cli_invalid_argument_value`, `cli_duplicate_argument`, `cli_unexpected_positional`, and `cli_invalid_utf8`. `message` names the offending argument and `hint` gives the command to run next; neither ever quotes a raw value, including secrets. These are decided before any config, secret source, filesystem, network, or domain I/O.
Domain failures (exit 1) carry their own stable `error.code` instead, drawn from whatever this tool defines rather than from the `cli_*` set. No error message quotes a raw value it was given — an error event is routinely logged, and the input may hold secrets.