Documentation Index
Fetch the complete documentation index at: https://docs.codezero.io/llms.txt
Use this file to discover all available pages before exploring further.
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
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.
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) |
--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 --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 | Keyring account name (requires --source keyring or 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 |
