Manage the PostgreSQL listeners that tell cordon which database connections to intercept and what credentials to inject.
All cordon listener subcommands accept --scope project|user to select which config file they target, matching cordon start and cordon setup. --config and --scope are mutually exclusive — passing both is an error. Resolution:
--config <path> — explicit path.--scope <scope> — resolves to the scope’s default config path (project → $CWD/cordon.toml, user → ~/.config/cordon/cordon.toml).- Neither flag — defaults to project scope (
$CWD/cordon.toml).
cordon listener add
Add a new PostgreSQL listener. With no flags, launches an interactive wizard that prompts for name, port, upstream address, username, secret source, and source-specific fields.
Non-interactive mode
Pass flags to skip the wizard:
cordon listener add --name local-pg --port 15432 --upstream db.example.com:5432 \
--username app_user --source keyring --account pg-password
| Flag | Description |
|---|
--name | Listener name |
--port | Local port to listen on (e.g. 15432) |
--upstream | Upstream PostgreSQL address (e.g. db.example.com:5432) |
--username | Database username |
--source | 1password or keyring |
--vault | 1Password vault name (requires --source 1password) |
--item | 1Password item name (requires --source 1password) |
--field | 1Password field name (requires --source 1password) |
--account | Keyring account name (requires --source keyring) |
--config | Path to cordon.toml (mutually exclusive with --scope) |
--scope | project (default) or user — selects which config file to edit |
Examples
# Interactive — wizard prompts for everything
cordon listener add
# Keyring-backed listener
cordon listener add --name local-pg --port 15432 \
--upstream db.example.com:5432 --username app_user \
--source keyring --account pg-password
# 1Password-backed listener
cordon listener add --name staging-db --port 15433 \
--upstream staging-db.internal:5432 --username deploy \
--source 1password --vault Infrastructure --item "Staging DB" --field password
# Add to the user-scope config
cordon listener add --scope user --name shared-pg --port 15434 \
--upstream shared.internal:5432 --username reader \
--source keyring --account shared-pg-password
After adding a keyring-backed listener, store the secret with cordon secret set ACCOUNT. Use cordon listener show NAME to find the keyring account. 1Password listeners don’t need this step — credentials are fetched from 1Password directly.
cordon listener edit
Edit an existing listener. With no flags (other than --scope or --config), launches an interactive editor that pre-fills current values — press Enter to keep a value, or type a new one.
cordon listener edit NAME
Non-interactive mode
Pass flags to change only specific fields without prompting:
cordon listener edit local-pg --port 15433
| Argument / Flag | Description |
|---|
NAME | Listener name to edit (positional, required) |
--port | New local port |
--upstream | New upstream address |
--username | New database username |
--source | 1password or keyring |
--vault | 1Password vault name (requires --source 1password or existing 1password source) |
--item | 1Password item name (requires --source 1password or existing 1password source) |
--field | 1Password field name (requires --source 1password or existing 1password source) |
--account | Keyring account name (requires --source keyring or existing keyring source) |
--config | Path to cordon.toml (mutually exclusive with --scope) |
--scope | project (default) or user — selects which config file to edit |
Partial updates
Non-interactive edit changes only the fields you specify. Unspecified fields keep their current values. Partial 1Password updates work the same as for routes:
# Change only the vault — item and field stay the same
cordon listener edit staging-db --vault NewVault
Switching secret sources
When switching from one source to another with --source:
- 1password to keyring:
--account defaults to the listener name if omitted
- keyring to 1password: requires
--vault, --item, and --field
Examples
# Interactive — pre-fills current values
cordon listener edit local-pg
# Change just the port
cordon listener edit local-pg --port 15433
# Change the upstream address
cordon listener edit local-pg --upstream new-db.internal:5432
# Switch source to keyring (account defaults to "local-pg")
cordon listener edit local-pg --source keyring
# Edit a listener in the user-scope config
cordon listener edit shared-pg --scope user
cordon listener list
List all configured listeners.
cordon listener list [--scope project|user] [--config path/to/cordon.toml]
| Option | Description |
|---|
--config | Path to cordon.toml (mutually exclusive with --scope) |
--scope | project (default) or user — selects which config file to read |
# List listeners in the user-scope config
cordon listener list --scope user
cordon listener show
Show details of a single listener.
cordon listener show NAME [--scope project|user] [--config path/to/cordon.toml]
| Argument / Option | Description |
|---|
NAME | Listener name to show |
--config | Path to cordon.toml (mutually exclusive with --scope) |
--scope | project (default) or user — selects which config file to read |
cordon listener remove
Remove a listener by name.
cordon listener remove NAME [--yes] [--scope project|user] [--config path/to/cordon.toml]
| Argument / Option | Description |
|---|
NAME | Listener name to remove |
--yes, -y | Skip confirmation prompt |
--config | Path to cordon.toml (mutually exclusive with --scope) |
--scope | project (default) or user — selects which config file to edit |
