Commands and interactive UI

Use the CLI for automation and quick tasks, or the interactive menu when you prefer guided steps. Credentials come from .env / DATABASE_URL, stored profiles, or interactive prompts when you run in a terminal. The query command also needs a target database (for example DB_NAME or a database in your connection URL).

CLI commands

Non-zero exit code on error.

Command	Description
`pgshell`, `pgshell ui`, `pgshell view`	Launch the interactive menu.
`pgshell query "<sql>"`	Run a raw SQL query. Supports `--json` / `--csv`.
`pgshell exec <file.sql>`	Run a SQL file against the target database.
`pgshell list`	List databases with sizes.
`pgshell create <name>`	Create a new database.
`pgshell drop <name>`	Drop a database. Use `--yes` to skip confirmation.
`pgshell table [dbName]`	List tables; optional database name or interactive pick.
`pgshell delete [dbName]`	Drop all tables in a database (with confirmation).
`pgshell doctor`	Connection health: latency, version, SSL, credential source.
`pgshell config show\|clear`	Inspect or clear the saved profile (password never printed).
`pgshell completion <shell>`	Print bash / zsh / powershell completion.

Global flags

--json, --csv, -q / --quiet — scripting-friendly output. Prefer --json when both --json and --csv are set.

Examples

pgshell query "SELECT * FROM users LIMIT 5" --json
pgshell exec ./seed.sql
pgshell list --csv
pgshell doctor --json
pgshell config show
eval "$(pgshell completion bash)"

Interactive menu

Run pgshell or pgshell ui.

Option	What it does
List all databases	Databases with sizes.
Create database	Create a new database.
Delete database	Drop a database with confirmation.
Switch database	Reconnect to another database.
List all tables	`public` schema: owner and row estimates.
View table data	Browse rows with a configurable limit.
Table structure	Columns, types, nullability, defaults.
Create new table	Define tables with column syntax.
Add new row	Insert with guided prompts.
Delete one table	Drop a single table with confirmation.
Delete all tables	Drop all `public` tables—extra confirmation.
Run custom SQL	Execute arbitrary SQL.
Recent queries	Re-run from local history (`~/.pgshell/history.json`).
Monitor active queries	Live view of running queries.
Disconnect and exit	Close the connection and quit.
Re-setup credentials	Update the stored password (for example after a password change).

Tips

Ctrl+C exits safely.
Blank insert fields can mean DEFAULT or NULL where applicable.
New table names and pgshell create database names: start with a letter or underscore; only letters, numbers, and underscores. The interactive Create database menu uses quoted SQL identifiers, so other valid PostgreSQL database names may work there.
Dangerous patterns are blocked in table creation flows.
If you drop the database you are connected to, PgShell reconnects to the postgres database automatically.

Something not working? See Troubleshooting.