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

> Print scope-aware env vars to route traffic through cordon.

Print the environment variables a consumer needs to route traffic through cordon. Use the output in your shell, `.envrc` (direnv), `.mise.toml`, or any tooling that consumes env vars.

## Usage

```bash theme={null}
cordon env [OPTIONS]
```

## Options

| Option | Description |
| - | - |
| `--scope` | Configuration scope: `project` (default) or `user` |
| `--config`, `-c` | Path to `cordon.toml` (overrides scope-resolved path) |
| `--format` | Output format: `shell` (default), `fish`, `dotenv`, `json` |
| `--refresh-ca-bundle` | Regenerate `combined-ca.pem` from the installed system CA bundle and the existing Cordon CA before printing env vars |

Unlike most config-reading commands, `--config` does not conflict with `--scope`; when provided, `--config` wins.

## Examples

Interactive shell (bash / zsh):

```bash theme={null}
eval "$(cordon env)"
```

fish:

```fish theme={null}
cordon env --format fish | source
```

direnv (`.envrc`):

```bash theme={null}
eval "$(cordon env)"
```

mise (`.mise.toml`):

```bash theme={null}
cordon env --format dotenv > .mise.cordon.env
```

JSON for scripting:

```bash theme={null}
cordon env --format json | jq .HTTPS_PROXY
```

## Refreshing the CA bundle

For the October 2026 security update, use the [complete upgrade checklist](https://docs.codezero.io/security/october-2026-upgrade.md) alongside the command reference below.

`combined-ca.pem` is a snapshot of the system CA bundle plus the Cordon CA. Update your system's CA certificate source first, then refresh each Cordon configuration whose clients use the combined bundle:

```bash theme={null}
cordon env --refresh-ca-bundle
cordon env --scope user --refresh-ca-bundle
cordon env --config /path/to/cordon.toml --refresh-ca-bundle
```

Refresh uses the same system-bundle discovery as `cordon setup`: the first readable bundle in the known Homebrew or OS certificate locations. It reads the installed file; it does not download roots or change OS trust settings. On macOS, updating Keychain alone may not update the Homebrew/OpenSSL PEM file that Cordon selects. The selected source path is printed to stderr after a successful refresh.

The output bundle is written alongside the configured CA certificate. Custom `[tls]` paths are honored, with relative paths resolved against the config file's directory. The existing Cordon CA certificate, private key, and config are preserved. This command does not generate or rotate the local CA, install services, or restart processes.

Refresh replaces the entire combined bundle, including any manual additions. Install custom roots in the selected system CA source before refreshing; additions made only to `combined-ca.pem` will be lost. Source PEM blocks must be standard `CERTIFICATE` blocks containing valid X.509 certificates. `TRUSTED CERTIFICATE` blocks and private-key blocks are rejected by bundle generation, including during setup. Text outside PEM blocks, such as system root descriptions, is retained.

Restart clients after refreshing so they reload the updated trust bundle. Clients using their own CA stores need those stores updated too. For unconfigured hosts, Cordon forwards an opaque CONNECT tunnel: the client validates the real server certificate, so updated client trust is required.

Refreshing does not itself implement certificate revocation checking. It only copies the currently installed roots and the existing Cordon CA into a new bundle.

All output formats remain available during refresh. Env vars go to stdout; refresh diagnostics go to stderr. Without `--refresh-ca-bundle`, `cordon env` only prints the existing environment configuration and does not refresh the bundle.

## Output

Vars emitted:

* `HTTPS_PROXY` / `HTTP_PROXY` (plus lowercase) — `http://<audience>:<token>@127.0.0.1:<port>` when token enforcement is active, otherwise `http://127.0.0.1:<port>` with a warning. `<audience>` is Cordon's local scope namespace, not an OAuth/OIDC audience claim.
* `NODE_EXTRA_CA_CERTS` — absolute path to the Cordon CA cert. Node.js expects a raw cert, not a bundle.
* `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` / `CURL_CA_BUNDLE` — absolute path to the combined (system + Cordon) CA bundle. These env vars *replace* the default trust store, so a bundle is required.
* JSON output is a flat object of environment variable names to string values, preserving compatibility with scripts that export every top-level entry.

> [!WARNING]
>
> Authenticated proxy URLs contain Cordon tokens. Do not commit or share them. See [Proxy Tokens](https://docs.codezero.io/guides/token-migration.md) for rotation and handling guidance.

See the [generic tool guide](https://docs.codezero.io/guides/generic.md) for where to apply these values and [SDK Compatibility](https://docs.codezero.io/guides/sdk-compatibility.md#runtime-ca-and-proxy-notes) for runtime-specific exceptions.

## Errors

* `no cordon.toml at <path> — run \`cordon setup\` first\` — no config at the resolved scope path.
* Bundle vars are omitted (with a comment) if `combined-ca.pem` is missing; run `cordon setup` to generate it.
* With `--refresh-ca-bundle`, disabled TLS, a missing or invalid Cordon CA, a missing/unreadable/invalid system bundle, or a bundle-write failure causes a nonzero exit with no env output and preserves any existing bundle. Correct the reported problem before retrying; refresh requires an existing CA from setup.
* Token loading and environment output happen after a successful bundle replacement. An error in those later steps can make the command fail even though the bundle was refreshed. Check stderr for the `Refreshed` message, resolve the error, and rerun the command.

## See also

* [`cordon setup`](https://docs.codezero.io/cli/setup) — generates the config and CA bundle this command depends on.
* [`cordon token`](https://docs.codezero.io/cli/token) — manage proxy authentication tokens.
* [Any tool (generic)](https://docs.codezero.io/guides/generic.md) — manual proxy environment setup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.