cordon listener

Manage the PostgreSQL listeners that tell cordon which database connections to intercept and what credentials to inject. Prefer these commands over editing cordon.toml directly. They validate listener ports, upstreams, TLS mode, and secret references, and are intended to make listener configuration safer and less error-prone. 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 --config <path> can create a default config skeleton when that explicit path is missing. With default project scope or --scope, run cordon setup first. Other listener subcommands require the resolved config file to already exist.

cordon listener add

Add a new PostgreSQL listener. With no flags, launches an interactive wizard that prompts for name, port, upstream address, client TLS mode, username, secret source, and source-specific fields.

cordon listener add

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`	1Password account selector with `--source 1password`; keyring account name with `--source keyring`
`--client-tls`	Client-to-Cordon TLS mode: `accept` (default), `require`, or `disable`
`--config`	Path to cordon.toml (mutually exclusive with `--scope`)
`--scope`	`project` (default) or `user` — selects which config file to edit

--client-tls require requires valid tls.ca_cert_path and tls.ca_key_path in cordon.toml. When client_tls is omitted, Cordon treats it as accept. Cordon always requires TLS from Cordon to the upstream PostgreSQL server before it sends startup or authentication data. There is no command-line or configuration option to disable upstream PostgreSQL TLS.

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

# Require local PostgreSQL client TLS
cordon listener add --name secure-pg --port 15435 \
  --upstream db.example.com:5432 --username app_user \
  --source keyring --account pg-password --client-tls require

# 1Password-backed listener
cordon listener add --name staging-db --port 15433 \
  --upstream staging-db.internal:5432 --username deploy \
  --source 1password --account my-team --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)
`--new-name`	Rename the listener
`--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`	1Password account selector with `--source 1password` or an existing 1Password source; keyring account name with `--source keyring` or an existing keyring source
`--client-tls`	Client-to-Cordon TLS mode: `accept`, `require`, or `disable`
`--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

# Rename a listener
cordon listener edit local-pg --new-name app-db

# Change the upstream address
cordon listener edit local-pg --upstream new-db.internal:5432

# Require local PostgreSQL client TLS
cordon listener edit local-pg --client-tls require

# 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

Getting Started

Configuration

Guides

CLI Reference

Security

cordon listener

cordon listener add

Non-interactive mode

Examples

cordon listener edit

Non-interactive mode

Partial updates

Switching secret sources

Examples

cordon listener list

cordon listener show

cordon listener remove

​cordon listener add

​Non-interactive mode

​Examples

​cordon listener edit

​Non-interactive mode

​Partial updates

​Switching secret sources

​Examples

​cordon listener list

​cordon listener show

​cordon listener remove

cordon listener add

Non-interactive mode

Examples

cordon listener edit

Non-interactive mode

Partial updates

Switching secret sources

Examples

cordon listener list

cordon listener show

cordon listener remove