ferrvault reads the secrets of one vault environment and prints them, or runs a command with them in its environment. It authenticates with a service-account token, so it sees exactly the environment that token is bound to.

Install

Binaries for Linux and macOS (amd64 and arm64) and Windows (amd64) are attached to each cli-v* release. On Linux or macOS:

version=cli-v0.2.0
os="$(uname -s | tr '[:upper:]' '[:lower:]')"
arch="$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')"
curl -fsSL "https://github.com/FerrLabs/FerrVault/releases/download/$version/ferrvault-$os-$arch.tar.gz" | tar -xz ferrvault
sudo install -m 0755 ferrvault /usr/local/bin/ferrvault

On Windows, download ferrvault-windows-amd64.zip from the same release and put ferrvault.exe on your PATH. On any platform you can also build from source with Cargo:

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

Log in

ferrvault login --url https://api.ferrvault.com

The token is read from standard input, or from --token or FERRVAULT_TOKEN. It is checked against the API before anything is stored, then kept in the operating system's credential store: Credential Manager on Windows, Keychain on macOS, libsecret on Linux. There is no fallback to a file on disk, so on Linux without a keyring login fails.

In CI, skip login and set FERRVAULT_URL and FERRVAULT_TOKEN in the environment. On GitHub Actions, the FerrVault action installs the CLI and exports the secrets you name as masked environment variables for the following steps:

- uses: FerrLabs/FerrVault/action@cli-v0.2.0
  with:
    api-url: https://api.ferrvault.com
    token: ${{ secrets.FERRVAULT_TOKEN }}
    cli-version: cli-v0.2.0
    names: DATABASE_URL,STRIPE_KEY

Use all: true instead of names to fetch every secret of the environment.

Commands

Command What it does
ferrvault whoami Shows the vault, role, label and expiry of the token.
ferrvault list Lists secret names and versions, never values.
ferrvault get NAME Prints one value.
ferrvault get --all Prints every value, as --format env, dotenv or json.
ferrvault get --names A,B Prints a subset.
ferrvault exec -- CMD Runs CMD with every secret as an environment variable.
ferrvault set NAME VALUE Creates a secret, or rotates it with --update. Needs writer.
ferrvault delete NAME Deletes a secret, keeping its versions. Needs writer.
ferrvault logout Forgets the stored URL and token.

ferrvault exec never writes values to disk, which makes it the safest way to hand secrets to a process:

ferrvault exec -- ./run-migrations.sh
ferrvault exec --names DATABASE_URL,STRIPE_KEY -- npm run start

Private deployments

Flag Effect
--ca-cert PATH Trusts an extra CA certificate (PEM).
--client-cert, --client-key Presents a client certificate for mutual TLS.
--pin-sha256 HASH Pins the server certificate by the SHA-256 of any certificate in its chain.

Each flag has a matching FERRVAULT_* environment variable; ferrvault --help lists them.