cordon route

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:

--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 route 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 route subcommands require the resolved config file to already exist.

cordon route add

Add a new route. With no flags, launches an interactive wizard that prompts for route match scope, auth, and secret fields.

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:

cordon route add --host api.stripe.com --auth-type header --header-name Authorization --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`	1Password account selector with `--source 1password` (sign-in address, shorthand, account UUID, or user UUID — run `op account list` to find valid values); keyring account name with `--source keyring`
`--username`	Username (requires `--auth-type basic`)
`--header-name`	Header name (requires `--auth-type header`; `Authorization` routes use the `Bearer` scheme automatically)
`--path-exact`	Match one exact normalized path, e.g. `/v1/comments`; mutually exclusive with `--path-glob`
`--path-glob`	Match variable path segments with `` and ``, e.g. `/v1//comments/**`; mutually exclusive with `--path-exact`
`--method`	Limit injection to HTTP methods; repeat or comma-separate values
`--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 route match scope, auth, and secret fields
cordon route add

# Bearer-style Authorization header with keyring
cordon route add --host api.openai.com --auth-type header --header-name Authorization --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 --account my-team --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 --source keyring --account stripe-live-key

# Scoped route for a subtree and method set
cordon route add --host api.stripe.com --path-glob '/v1/**' \
  --method POST --method PATCH \
  --auth-type header --header-name Authorization --source keyring --account stripe-write-key

# Scoped route with variable path segments
cordon route add --host api.stripe.com --path-glob '/v1/*/comments/**' \
  --auth-type header --header-name Authorization --source keyring --account stripe-comments-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 --source keyring --account openai

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.

The interactive wizard infers path_exact vs path_glob from input syntax: a value containing * or ** becomes path_glob, anything else becomes path_exact. To configure a path_exact value that contains a literal * (rare — e.g. when matching a request path that includes percent-encoded %2A), use the --path-exact flag instead of the wizard.

The 0.4.0 --path-prefix flag is still accepted for compatibility but hidden from help. Prefer --path-glob '/v1/**' for new routes. Legacy prefixes are converted to glob syntax only when the conversion preserves the same match behavior.

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.

cordon route edit NAME

Non-interactive mode

Pass flags to change only specific fields without prompting:

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`	1Password account selector with `--source 1password` or an existing 1Password source (sign-in address, shorthand, account UUID, or user UUID — run `op account list` to find valid values); keyring account name with `--source keyring` or an existing keyring source
`--username`	Username (requires `--auth-type basic`)
`--header-name`	Header name (requires `--auth-type header`; `Authorization` routes use the `Bearer` scheme automatically when the header is changed with the CLI)
`--path-exact`	Set an exact-path matcher; mutually exclusive with `--path-glob`
`--path-glob`	Set a path-glob matcher; mutually exclusive with `--path-exact`
`--clear-path`	Clear any configured path matcher
`--method`	Replace the HTTP method scope; repeat or comma-separate values
`--clear-methods`	Clear the HTTP method scope
`--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:

# 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

# 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

# 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

# Change route scope
cordon route edit stripe --path-exact /v1/comments --method POST

# Clear route scope
cordon route edit stripe --clear-path --clear-methods

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

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

# List routes in the user-scope config
cordon route list --scope user

cordon route show

Show details of a single route.

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.

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

Getting Started

Configuration

Guides

CLI Reference

Security

cordon route add

Non-interactive mode

Examples

cordon route edit

Non-interactive mode

Partial updates

Switching secret sources

Examples

cordon route list

cordon route show

cordon route remove

​cordon route add

​Non-interactive mode

​Examples

​cordon route edit

​Non-interactive mode

​Partial updates

​Switching secret sources

​Examples

​cordon route list

​cordon route show

​cordon route remove

cordon route add

Non-interactive mode

Examples

cordon route edit

Non-interactive mode

Partial updates

Switching secret sources

Examples

cordon route list

cordon route show

cordon route remove