Skip to content

README.md

Latest commit

 

History

History
90 lines (65 loc) · 3.77 KB

README.md

File metadata and controls

90 lines (65 loc) · 3.77 KB
Raw

ferrvault CLI

Consumer CLI for FerrVault. Fetch secrets from your FerrVault tenant and inject them into a process without ever writing them to disk.

Install

Binary releases for Linux, macOS, and Windows ship at releases. From source:

cargo install --git https://github.com/FerrLabs/FerrVault ferrvault-cli

First login

# Stores the URL and token in the OS keyring. No file on disk.
ferrvault login --url https://api.ferrvault.example.com
# token will be read from stdin if not passed via --token / FERRVAULT_TOKEN

The login flow validates the token against /v1/operator/me before storing anything, so a typo fails loudly instead of silently.

Commands

Command What it does
ferrvault login Store url + token in OS keyring.
ferrvault logout Forget url + token.
ferrvault whoami [--json] Show the bound vault, role, label, and expiry.
ferrvault list [--json] List secret names + current version (no values).
ferrvault get NAME Print a single secret value to stdout.
ferrvault get --all Print every secret (with --format env/dotenv/json).
ferrvault get --names A,B,C Fetch a subset.
ferrvault exec -- CMD ... Run CMD with every secret injected as env var; never writes to disk.
ferrvault set NAME VALUE Create a secret. --stdin reads from stdin, --from-file <path> reads from a file, --update rotates an existing secret instead of erroring. Requires SAT role ≥ Writer.
ferrvault delete NAME Soft-delete a secret (versions are kept). Asks for typed confirmation unless --yes is passed. Requires SAT role ≥ Writer.

Security flags

Flag Effect
--ca-cert PATH Add a CA cert (PEM) to the trust store. For private deployments.
--client-cert / --client-key mTLS — client certificate + key (PEM).
`--pin-sha256 HEX BASE64`
--insecure-skip-verify Skip TLS validation. Requires FERRVAULT_INSECURE_I_KNOW_WHAT_I_AM_DOING=yes in env (belt-and-suspenders so a forgotten dev flag can't leak a SAT). Never use in production.

Every flag has a matching FERRVAULT_* environment variable. See ferrvault --help for the full list.

Examples

Run a job with secrets injected:

ferrvault exec -- ./run-migrations.sh

Generate a .env file from secrets in the vault:

ferrvault get --all --format dotenv > .env.staging

Use only a subset for one specific command:

ferrvault exec --names DATABASE_URL,STRIPE_KEY -- npm run start

Storage

The token is stored in the OS-native credential store:

  • Windows → DPAPI / Credential Manager
  • macOS → Keychain
  • Linux → libsecret (Secret Service) — install gnome-keyring or keepassxc if you don't already have one.

There is no fallback to a plain file on disk. If no keyring is available, login fails loudly. CI environments should pass the token via FERRVAULT_TOKEN instead of using login.

Threat model

See docs/SECURITY-THREAT-MODEL.md at the repo root.