Commands
Generated from each command's --help, so it always matches the tool.
pgembed
Description:
Run PostgreSQL locally: named instances of any version, SQL, schema, and an MCP server.
Usage:
pgembed [command] [options]
Options:
-h, --help Show help and usage information
--version Show version information
Commands:
versions List the Postgres versions published for this platform
install <version> Download and extract a Postgres version into the cache
extensions <version> List the extensions CREATE EXTENSION can use in a version
start <name> Start a named instance in the background (created on first start)
stop [<names>] Stop instances cleanly
kill [<names>] Force-kill instances (last resort)
restart <name> Stop and start an instance with its saved settings
status [<names>] (list) Show instances: version, port, process, state, uptime, data size
connstr <name> Print an instance's connection string
logs <name> Show an instance's server log
rm [<names>] Delete instances and their data
sql [<target>] [<sql>] Run SQL against an instance and show the results
format [<sql>] Format SQL, keeping comments; needs no server
schema <target> [<table>] List tables, or describe one: columns, keys, indexes, constraints
mcp Run an MCP server over standard input and output, for AI assistants
doctor Check that Postgres can run here
cache Inspect and clean the download cacheInstances
start
Description:
Start a named instance in the background (created on first start)
Examples:
pgembed start app --version 17
pgembed start ci --version 16,17,18
Usage:
pgembed start <name> [options]
Arguments:
<name> Instance name; with several versions, the prefix: <name>-<major>
Options:
-v, --version <VERSION> Version for a new instance (17, 17.6, 17.6.0, latest), or several:
16,17,18. Kept for later starts
-p, --port <PORT> Port (default: the instance's remembered port, else 5432 if free, else a
free port)
--param <KEY=VALUE> Postgres setting, for example --param max_connections=300. Repeatable
--extension <URL> Extension zip to install; append #sha256=<hex> to verify it. Repeatable
--password Require a password for TCP connections, for shared machines: pgembed
generates it and keeps it in the instance's private settings; pgembed
connstr prints it
--locale <LOCALE> Locale for a new instance's data (default: en_US.UTF-8; on Linux without
it, C.UTF-8)
--foreground Stay attached and stream the log; Ctrl+C stops the server
--refresh Check for new versions now
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR,
else the per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven
Central, or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationstatus
Description:
Show instances: version, port, process, state, uptime, data size
Usage:
pgembed status [<names>...] [options]
Arguments:
<names> Instance names or patterns (default: all)
Options:
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationconnstr
Description:
Print an instance's connection string
Examples:
pgembed connstr app --format uri
Usage:
pgembed connstr <name> [options]
Arguments:
<name>
Options:
--db <DATABASE> Database (default: postgres)
--schema <SCHEMA> Schema to put first on the search path
--format <FORMAT> Only this format, unlabelled: npgsql, uri, libpq, jdbc or env. Default: all of
them
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationlogs
Description:
Show an instance's server log
Examples:
pgembed logs app --follow
Usage:
pgembed logs <name> [options]
Arguments:
<name>
Options:
-n, --tail <LINES> Lines from the end (default: 50)
-f, --follow Keep printing new lines until Ctrl+C
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationstop
Description:
Stop instances cleanly
Examples:
pgembed stop app
pgembed stop --all
Usage:
pgembed stop [<names>...] [options]
Arguments:
<names> Instance names; * and ? match several, for example ci-*
Options:
--all Every instance
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationrestart
Description:
Stop and start an instance with its saved settings
Usage:
pgembed restart <name> [options]
Arguments:
<name>
Options:
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationkill
Description:
Force-kill instances (last resort)
Examples:
pgembed kill app
Usage:
pgembed kill [<names>...] [options]
Arguments:
<names> Instance names; * and ? match several, for example ci-*
Options:
--all Every instance
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationrm
Description:
Delete instances and their data
Examples:
pgembed rm demo
Usage:
pgembed rm [<names>...] [options]
Arguments:
<names> Instance names; * and ? match several, for example ci-*
Options:
--force Stop a running instance first
-y, --yes Delete without asking
--all Every instance
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationSQL and schema
sql
Description:
Run SQL against an instance and show the results
Examples:
pgembed sql app "SELECT version()"
pgembed sql app -f seed.sql
pgembed sql --check -f migrate.sql
Usage:
pgembed sql [<target>] [<sql>] [options]
Arguments:
<target> An instance name, or a connection string: Npgsql, postgresql:// URI, libpq key=value or
JDBC. Not needed with --check
<sql> SQL to run; or use -f, or pipe it in. Without any, opens an interactive prompt
Options:
-f, --file <PATH> Run a SQL file
--db <DATABASE> Database (default: postgres for an instance, else the connection string's)
--schema <SCHEMA> Schema for unqualified names (sets the search path)
--format <FORMAT> table (fits the terminal; the default there), aligned (psql-style, one row per
line; the default when output is redirected), json, csv or markdown
--max-rows <N> Rows shown per result in table format (default: 500); other formats return all
--timing Show how long each statement took
--check Check the syntax and summarize each statement (tables, functions, whether it
asks first); needs no server
--no-pager Never open a pager (default: a result taller than the terminal opens in
PGEMBED_PAGER, PAGER or less -SFX)
-y, --yes Run statements that change the schema or existing rows without asking
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationschema
Description:
List tables, or describe one: columns, keys, indexes, constraints
Examples:
pgembed schema app
pgembed schema app books
pgembed schema app orders --schema sales --json
Usage:
pgembed schema <target> [<table>] [options]
Arguments:
<target> An instance name, or a connection string: Npgsql, postgresql:// URI, libpq key=value or
JDBC
<table> A table or view to describe; * and ? describe every match. Without it, lists the tables
and views
Options:
--db <DATABASE> Database (default: postgres for an instance, else the connection string's)
--schema <SCHEMA> Only this schema; unqualified table names are looked up in it
--format <FORMAT> table (the default in a terminal), aligned (the default when redirected), csv
or markdown; --json for structured output
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationformat
Description:
Format SQL, keeping comments; needs no server
Examples:
pgembed format "select * from t where id=1"
pgembed format -f schema.sql --write
pgembed format -f a.sql -f b.sql --check
Usage:
pgembed format [<sql>] [options]
Arguments:
<sql> SQL to format; or use -f, or pipe it in
Options:
-f, --file <PATH> A SQL file to format; repeat for several
--write Rewrite the files in place
--check Only list the files that are not formatted; exit 1 if any
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationVersions and cache
versions
Description:
List the Postgres versions published for this platform
Examples:
pgembed versions
pgembed versions --major 17
Usage:
pgembed versions [options]
Options:
--major <MAJOR> Every published version of one major, for example 17
--all Every published version
--platform <RID> Another platform: win-x64, linux-x64, linux-arm64, linux-musl-x64,
linux-musl-arm64, osx-x64, osx-arm64
--refresh Check for new versions now instead of using the cached list
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationinstall
Description:
Download and extract a Postgres version into the cache
Examples:
pgembed install 17
Usage:
pgembed install <version> [options]
Arguments:
<version> Exact (17.6.0), major (17), minor (17.6) or latest
Options:
--extension <URL> Extension zip to install with it; append #sha256=<hex> to verify it.
Repeatable
--refresh Check for new versions now
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationextensions
Description:
List the extensions CREATE EXTENSION can use in a version
Examples:
pgembed extensions 17
Usage:
pgembed extensions <version> [options]
Arguments:
<version> Exact (17.6.0), major (17), minor (17.6) or latest
Options:
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationcache list
Description:
Cached installs and downloads, with sizes
Usage:
pgembed cache list [options]
Options:
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationcache clean
Description:
Remove cached versions (never ones in use)
Examples:
pgembed cache clean --keep-latest
Usage:
pgembed cache clean [options]
Options:
--keep-latest Keep only the newest version of each major
--version <SPEC> Remove one version or major, for example 15 or 16.4.0
--all Remove everything that is not in use
--dry-run Only show what would be removed
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationdoctor
Description:
Check that Postgres can run here
Usage:
pgembed doctor [options]
Options:
--dir <PATH> Check that Postgres can use this folder (default: the cache folder)
--port <PORT> Check that this port is free (default: 5432)
--cache-dir <PATH> Cache folder for downloads and instances (default: PGEMBED_CACHE_DIR, else the
per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries (default: Maven Central,
or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage informationMCP
mcp
Description:
Run an MCP server over standard input and output, for AI assistants
Examples:
pgembed mcp
pgembed mcp --read-only
Usage:
pgembed mcp [options]
Options:
--read-only Refuse anything that writes, on every target
--no-confirm Run changes, kills and removals without asking (for
sandboxes and throwaway agents)
--allow-external-writes Allow writes to servers pgembed did not start (named
connections and connection strings); read-only otherwise
--statement-timeout <SECONDS> Seconds a statement may run before it is cancelled (default
120; 0 for none)
--least-privilege Connect to pgembed instances as a role that is not a
superuser (PostgreSQL 14+): it reads, writes and creates,
but cannot reach files, programs or libraries, even through
functions; it cannot alter tables the superuser owns
--connection <NAME=CONNECTION_STRING> A server the assistant can use by name without seeing its
connection string or password, for example --connection
prod=postgresql://me@db/shop. Repeatable
--cache-dir <PATH> Cache folder for downloads and instances (default:
PGEMBED_CACHE_DIR, else the per-user cache folder)
--maven-repo <URL> Maven repository or mirror with the Postgres binaries
(default: Maven Central, or PGEMBED_MAVEN_REPO)
--json Machine-readable output
--verbose Log details to standard error
-h, --help Show help and usage information