Manage Cloudflare credentials without keeping them in shell profiles, dotfiles or CI variables. cf-vault signs you in, keeps the session in your system keychain, and runs a command with short-lived Cloudflare credentials in its environment for that command only. It is inspired by aws-vault and nix-vault.
Warning
Pre-1.0. The configuration file's keys and the command line may still change between minor versions.
cf-vault login -p production # once: browser sign-in
cf-vault exec -p production -- terraform plan # credentials exist only for this commandsequenceDiagram
participant You
participant Vault as cf-vault
participant Store as Keychain
participant IdP as Identity provider
participant Broker as Token broker
participant Cmd as terraform plan ...
You->>Vault: login -p production (once)
Vault->>IdP: browser sign-in (authorization code + PKCE)
Vault->>Store: save the session
You->>Vault: exec -p production -- terraform plan
Vault->>Store: read (renew if expiring)
Vault->>Broker: exchange the ID token (RFC 8693)
Broker-->>Vault: short-lived API token, R2 credentials
Vault->>Cmd: run with the credentials in its environment
Cmd-->>Vault: exits
Vault->>Broker: release the token (RFC 7009)
The session lives in the keychain. The command gets the credentials in its own environment and nothing else does: no shell profile, dotfile or CI variable holds them. Profiles without a broker skip the exchange and deliver the stored API token, or temporary R2 credentials derived from it.
| You want | Use | Read |
|---|---|---|
| Team access with policy-scoped, short-lived tokens and R2 credentials | an oauth2 profile with exchange at a cloudflare-sts broker, or any other RFC 8693 broker |
Broker |
| A broker that publishes metadata | issuer instead of the endpoints |
Endpoint discovery |
| Your own identity provider, or Cloudflare's own sign-in with your own client | an oauth2 profile with issuer and client_id |
Cloudflare OAuth |
| A plain API token kept in the keychain | an api_token profile |
Configuration |
| Temporary R2 credentials, from a broker, an API token or Cloudflare's own OAuth | an [r2] table, or a broker bucket |
R2 |
| CI, or a machine with no keychain | environment variables | CI |
Every guide is in docs/.
nix run github:cf-contrib/cf-vault -- --help # or: nix profile install github:cf-contrib/cf-vault
cargo binstall cf-vault # prebuilt binary from the GitHub release
cargo install cf-vaultSupported: macOS and Linux. On Linux the session goes to the Secret Service (for example
gnome-keyring or KeePassXC), so one must be running in your session. cf-vault never falls back to
another store: without a usable keychain, login fails. A machine without one uses environment
variables: see CI.
- Write a profile in
~/.config/cf-vault/config.toml:[production] type = "oauth2" account_id = "xyz789" [production.oauth2.exchange] issuer = "https://cloudflare-sts-api.example.com" # the broker; its metadata names the rest scopes = ["infra-admins:tofu-plan"] # what to ask the broker for
- Log in once:
cf-vault login -p production. A browser step signs you in; anapi_tokenprofile asks for a hidden token instead. - Run a command with it:
cf-vault exec -p production --ttl 30m -- terraform plan. - Check with
cf-vault list: names, types, accounts and session state, never a secret.
The file never holds tokens or secrets, and the whole file is validated before any command runs.
A broker that publishes metadata is named with issuer; one that does not is named by its
token_endpoint: see endpoint discovery. Every key is
in Configuration; a full example is
config.example.toml.
cf-vault login -p <name> [--no-browser] sign in, or store an API token
cf-vault exec -p <name> [--ttl 10m] -- <command> ... run a command with the credentials
cf-vault logout -p <name> remove the stored session
cf-vault list [--json] profiles and session state
What each does, the variables the command receives and the exit statuses are in Commands.
- Cleanup is best effort after
SIGKILL: a broker token is then not released and expires on its own. - Credentials are not renewed while the command runs; ask for a longer lifetime with
--ttl. - R2 credentials cannot be revoked early.
- Cloudflare's own sign-in needs a client of your own for now, and R2 credentials from it need the
account-api-tokens.writescope.
The full list is in docs/limitations.md.
nix develop # pinned Rust toolchain
cargo fmt --check && cargo clippy --all-targets --features test-store -- -D warnings
cargo test --features test-store # unit + integration tests
cargo test -- --ignored keyring_smoke # real keychain round trip (manual)The integration tests drive the real binary against loopback mock servers (an OIDC provider, a
broker and the Cloudflare API) with fake credentials only. They need the test-store cargo
feature, which adds test hooks selected by CF_VAULT_* variables. It is never enabled by default
or in releases, and CI fails if a release binary contains any of them.
MIT, see LICENSE.