> ## 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.

# cordon listener

> Add, edit, list, show, and remove PostgreSQL listeners in cordon.toml.

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:

1. `--config <path>` — explicit path.
2. `--scope <scope>` — resolves to the scope's default config path (project → `$CWD/cordon.toml`, user → `~/.config/cordon/cordon.toml`).
3. 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.

```bash theme={null}
cordon listener add
```

### Non-interactive mode

Pass flags to skip the wizard:

```bash theme={null}
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

```bash theme={null}
# 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
```

<Tip>
  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.
</Tip>

## 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.

```bash theme={null}
cordon listener edit NAME
```

### Non-interactive mode

Pass flags to change only specific fields without prompting:

```bash theme={null}
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:

```bash theme={null}
# 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

```bash theme={null}
# 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.

```bash theme={null}
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 |

```bash theme={null}
# List listeners in the user-scope config
cordon listener list --scope user
```

## cordon listener show

Show details of a single listener.

```bash theme={null}
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.

```bash theme={null}
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 |