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

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

Manage the routes that tell cordon which hosts to intercept and what credentials to inject.

Prefer these commands over editing `cordon.toml` directly. They validate the route shape, preserve existing config, and are intended to make route configuration safer and less error-prone.

All `cordon route` 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 route add

Add a new route. With no flags, launches an interactive wizard that prompts for host, route name, auth type, secret source, and source-specific fields.

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

### Non-interactive mode

Pass flags to skip the wizard. Requires `--host`, `--auth-type`, `--source`, and the fields required by the selected auth type and secret source:

```bash theme={null}
cordon route add --host api.stripe.com --auth-type header --header-name Authorization --scheme Bearer --source keyring --account stripe-key
```

| Flag            | Description                                                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------- |
| `--host`        | Hostname to match (e.g. `api.stripe.com`)                                                                |
| `--name`        | Route name (defaults to derived from host)                                                               |
| `--auth-type`   | `header` or `basic`                                                                                      |
| `--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`)                                                       |
| `--username`    | Username (requires `--auth-type basic`)                                                                  |
| `--header-name` | Header name (requires `--auth-type header`)                                                              |
| `--scheme`      | Optional header auth scheme (requires `--auth-type header`; required with `--header-name Authorization`) |
| `--config`      | Path to cordon.toml (mutually exclusive with `--scope`)                                                  |
| `--scope`       | `project` (default) or `user` — selects which config file to edit                                        |

### Examples

```bash theme={null}
# Interactive — wizard prompts for everything
cordon route add

# Bearer-style Authorization header with keyring
cordon route add --host api.openai.com --auth-type header --header-name Authorization --scheme Bearer --source keyring --account openai

# Raw API-key header with 1Password
cordon route add --host api.anthropic.com --auth-type header --header-name x-api-key \
  --source 1password --vault Engineering --item "Anthropic API Key" --field credential

# Basic auth with keyring
cordon route add --host db.example.com --auth-type basic --username admin \
  --source keyring --account db-password

# Custom route name
cordon route add --host api.stripe.com --name stripe-live \
  --auth-type header --header-name Authorization --scheme Bearer --source keyring --account stripe-live-key

# Add to the user-scope config (~/.config/cordon/cordon.toml)
cordon route add --scope user --host api.openai.com \
  --auth-type header --header-name Authorization --scheme Bearer --source keyring --account openai
```

<Tip>
  After adding a keyring-backed route, store the secret with `cordon secret set ACCOUNT`. Use `cordon route show NAME` to find the keyring account for a route. 1Password routes don't need this step — credentials are fetched from 1Password directly.
</Tip>

## cordon route edit

Edit an existing route. 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 route edit NAME
```

### Non-interactive mode

Pass flags to change only specific fields without prompting:

```bash theme={null}
cordon route edit stripe --host api2.stripe.com
```

| Argument / Flag | Description                                                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------- |
| `NAME`          | Route name to edit (positional, required)                                                                |
| `--new-name`    | Rename the route                                                                                         |
| `--host`        | New hostname                                                                                             |
| `--auth-type`   | `header` or `basic`                                                                                      |
| `--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)                            |
| `--username`    | Username (requires `--auth-type basic`)                                                                  |
| `--header-name` | Header name (requires `--auth-type header`)                                                              |
| `--scheme`      | Optional header auth scheme (requires `--auth-type header`; required with `--header-name Authorization`) |
| `--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.

For 1Password sources, you can update individual sub-fields without repeating the others:

```bash theme={null}
# Change only the vault — item and field stay the same
cordon route edit stripe --vault NewVault
```

### Switching secret sources

When switching from one source to another with `--source`:

* **1password to keyring**: `--account` defaults to the route name if omitted
* **keyring to 1password**: requires `--vault`, `--item`, and `--field`

```bash theme={null}
# Switch from 1password to keyring (account defaults to "stripe")
cordon route edit stripe --source keyring

# Switch from keyring to 1password
cordon route edit stripe --source 1password --vault Eng --item "Stripe" --field token
```

### Examples

```bash theme={null}
# Interactive — pre-fills current values, press Enter to keep
cordon route edit stripe

# Change just the host
cordon route edit stripe --host api2.stripe.com

# Rename a route
cordon route edit stripe --new-name stripe-live

# Switch auth type (basic requires --username)
cordon route edit stripe --auth-type basic --username admin

# Update keyring account
cordon route edit stripe --account new-stripe-key

# Edit a route in the user-scope config
cordon route edit stripe --scope user
```

## cordon route list

List all configured routes.

```bash theme={null}
cordon route 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 routes in the user-scope config
cordon route list --scope user
```

## cordon route show

Show details of a single route.

```bash theme={null}
cordon route show NAME [--scope project|user] [--config path/to/cordon.toml]
```

| Argument / Option | Description                                                       |
| ----------------- | ----------------------------------------------------------------- |
| `NAME`            | Route name to show                                                |
| `--config`        | Path to cordon.toml (mutually exclusive with `--scope`)           |
| `--scope`         | `project` (default) or `user` — selects which config file to read |

## cordon route remove

Remove a route by name.

```bash theme={null}
cordon route remove NAME [--yes] [--scope project|user] [--config path/to/cordon.toml]
```

| Argument / Option | Description                                                       |
| ----------------- | ----------------------------------------------------------------- |
| `NAME`            | Route 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 |