Using the Revaulter CLI

The Revaulter CLI (revaulter-cli) is the primary way to submit encrypt, decrypt, and sign requests. It ensures requests are End-to-End Encrypted as they are sent to the server.

Installing the CLI#

Pre-compiled binary (recommended)#

Download the latest release from GitHub Releases. Binaries are available for Linux, macOS, Windows, and FreeBSD.

Each release also includes a checksums.txt with the SHA-256 of every archive and an attestations.json holding the build provenance for each asset. To check an archive before extracting it:

gh attestation verify revaulter-<version>-<platform>.tar.gz \
  --repo ItalyPaleAle/revaulter

Pass --bundle attestations.json to verify against the downloaded bundle instead of querying GitHub’s attestations API.

Each binary also has a CycloneDX SBOM listing the dependencies compiled into it, named revaulter-<version>-<platform>-<binary>.cdx.json. The server’s SBOM also lists the npm packages of the web client it embeds. The SBOMs are covered by checksums.txt and the attestations too.

Docker#

Mount a volume at /data to keep the trust store between runs. Pin the server’s anchor once, with -it so the CLI can ask for confirmation:

docker run --rm -it \
  -v revaulter-trust:/data \
  ghcr.io/italypaleale/revaulter-cli:2 trust \
  --server https://revaulter.example.com \
  --request-key AbCdEf0123456789GhIj

Every later command reuses that pin:

docker run --rm \
  -v revaulter-trust:/data \
  ghcr.io/italypaleale/revaulter-cli:2 encrypt \
  --server https://revaulter.example.com \
  --request-key AbCdEf0123456789GhIj \
  --key-label my-key \
  --algorithm A256GCM \
  --value SGVsbG8

Commands that read a file or write their output to one also need the directory mounted, for example -v "$PWD:/work". The container runs as a non-root user (UID 65532), so that user must be able to read and write those files.

Commands#

encrypt#

Submit an encryption request for approval.

revaulter-cli encrypt [flags]

Example (raw string):

revaulter-cli encrypt \
  --server https://revaulter.example.com \
  --request-key AbCdEf0123456789GhIj \
  --key-label boot-disk \
  --algorithm A256GCM \
  --message "Hello, world" \
  --note "boot unlock"

Example (read plaintext from a file):

revaulter-cli encrypt \
  --server https://revaulter.example.com \
  --request-key AbCdEf0123456789GhIj \
  --key-label boot-disk \
  --algorithm A256GCM \
  --input ./secret.bin

Example (JSON input):

echo '{"value":"SGVsbG8"}' | revaulter-cli encrypt \
  --server https://revaulter.example.com \
  --request-key AbCdEf0123456789GhIj \
  --key-label boot-disk \
  --algorithm A256GCM \
  --json -

decrypt#

Submit a decryption request for approval.

revaulter-cli decrypt [flags]

Example:

revaulter-cli decrypt \
  --server https://revaulter.example.com \
  --request-key AbCdEf0123456789GhIj \
  --key-label boot-disk \
  --algorithm A256GCM \
  --value <base64-ciphertext> \
  --nonce <base64-nonce> \
  --tag <base64-tag>

Example (JSON input, piping the output of encrypt):

revaulter-cli encrypt --message "secret" ... \
  | revaulter-cli decrypt \
    --server https://revaulter.example.com \
    --request-key AbCdEf0123456789GhIj \
    --json - \
    --format raw

Example (write the plaintext to a file):

revaulter-cli decrypt \
  --server https://revaulter.example.com \
  --request-key AbCdEf0123456789GhIj \
  --key-label boot-disk \
  --algorithm A256GCM \
  --value <base64-ciphertext> \
  --nonce <base64-nonce> \
  --tag <base64-tag> \
  --output /tmp/decrypted.bin \
  --format raw

sign#

Submit a signing request for approval. The CLI derives the bytes sent to the browser from the selected signing algorithm:

• ES256: the CLI hashes the input with SHA-256 and sends the 32-byte digest
• Ed25519: the CLI sends the raw message bytes, up to 100 KB
• Ed25519ph: the CLI hashes the input with SHA-512 and sends the 64-byte digest

revaulter-cli sign [flags]

Examples:

Sign a file (default output is a JSON envelope containing the base64url r || s signature):

revaulter-cli sign \
  --server https://revaulter.example.com \
  --request-key AbCdEf0123456789GhIj \
  --key-label release-signing \
  --algorithm ES256 \
  --input manifest.json

Sign data piped from stdin:

echo "hello" | revaulter-cli sign \
  --server https://revaulter.example.com \
  --request-key AbCdEf0123456789GhIj \
  --key-label release-signing \
  --algorithm ES256 \
  --input -

Sign a pre-computed SHA-256 digest, for tools that already hash the data:

revaulter-cli sign \
  --server https://revaulter.example.com \
  --request-key AbCdEf0123456789GhIj \
  --key-label release-signing \
  --algorithm ES256 \
  --digest d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592

Emit a compact JWS over a file, merging a custom kid into the protected header:

revaulter-cli sign \
  --server https://revaulter.example.com \
  --request-key AbCdEf0123456789GhIj \
  --key-label release-signing \
  --algorithm ES256 \
  --input manifest.json \
  --format jws \
  --jws-header '{"kid":"release-signing-2026"}'

Write only the raw 64-byte r || s signature to a file, for pipelines that verify with a separate tool:

revaulter-cli sign \
  --server https://revaulter.example.com \
  --request-key AbCdEf0123456789GhIj \
  --key-label release-signing \
  --algorithm ES256 \
  --input manifest.json \
  --format raw \
  --output manifest.sig

ECDSA signatures are non-deterministic: each one uses a fresh random k (per FIPS 186-5). Signing the same input twice produces two different signatures, and both are valid.

Ed25519 signatures are deterministic for a fixed key and message.

trust#

Pin a Revaulter server’s anchor public keys in the local trust store using TOFU (Trust On First Use).

revaulter-cli trust [flags]

The CLI fetches the server’s hybrid anchor bundle (ES384 + ML-DSA-87), verifies its signatures, and pins the anchor fingerprint. Subsequent commands (encrypt, decrypt, sign, ssh-agent) verify the pinned anchor and refuse to proceed if it changes unexpectedly. If the anchor is already pinned and matches, the command verifies it and exits successfully.

Run this once when first connecting to a server. In interactive use, the CLI shows the fingerprint and asks for confirmation. For non-interactive use, pass --yes to accept the key without checking the fingerprint.

The default trust store path is <user-config-dir>/revaulter-cli/trust.json (e.g. ~/.config/revaulter-cli/trust.json on Linux). Override it with the TRUST_STORE_PATH environment variable or the --trust-store flag.

Example (interactive, asks for confirmation):

revaulter-cli trust \
  --server https://revaulter.example.com \
  --request-key AbCdEf0123456789GhIj

Example (non-interactive, pins without asking):

revaulter-cli trust \
  --server https://revaulter.example.com \
  --request-key AbCdEf0123456789GhIj \
  --yes

The encrypt, decrypt, sign, and ssh-agent commands also accept --trust-store to point at a non-default trust store, and --no-trust-store to skip anchor verification entirely (equivalent to SSH’s StrictHostKeyChecking=no).

ssh-agent#

Run a local SSH agent that routes signing requests through Revaulter. Available on Unix systems only (Linux, macOS, BSD).

revaulter-cli ssh-agent [flags]

The agent listens on a Unix socket. SSH clients with SSH_AUTH_SOCK pointing at the socket send each signing request through Revaulter, where the key holder approves it in the browser with a passkey. The private key never leaves the browser: the server stores only public keys, and the agent receives only signatures. The signing key for --key-label must already be published: create and publish it in the web UI under Settings → Signing keys.

Pin the server anchor with revaulter-cli trust before running the agent, especially in non-interactive environments.

For a full setup walkthrough (including installing the public key in authorized_keys), see Authenticate to SSH servers.

Example:

revaulter-cli ssh-agent \
  --server https://revaulter.example.com \
  --request-key AbCdEf0123456789GhIj \
  --key-label ssh-main \
  --algorithm ES256

On startup the agent prints an export SSH_AUTH_SOCK=... line on stderr; evaluate it in the shell where you will use ssh:

export SSH_AUTH_SOCK='/run/user/1000/revaulter/ssh-agent-ssh-main.sock'
ssh user@prod.example.com

To list the SSH public key managed by the agent (for example to copy into ~/.ssh/authorized_keys):

SSH_AUTH_SOCK=/run/user/1000/revaulter/ssh-agent-ssh-main.sock ssh-add -L

The agent stops on Ctrl-C or SIGTERM and removes its socket on exit.

check#

Verify that a Revaulter server serves unmodified web client assets, as signed by Revaulter’s release workflow. See Verifying the web client’s integrity for the trust model and when to run this.

revaulter-cli check --server https://revaulter.example.com

version#

Print the CLI version.

revaulter-cli version

Reading the request key from a file#

Every command that connects to a server accepts the request key either inline with --request-key, or from a file with --request-key-file. The two flags are mutually exclusive, and exactly one of them is required.

install -m 600 /dev/null /etc/revaulter/request-key
echo -n 'AbCdEf0123456789GhIj' > /etc/revaulter/request-key

revaulter-cli decrypt \
  --server https://revaulter.example.com \
  --request-key-file /etc/revaulter/request-key \
  --json encrypted-key.json

Authenticating with an OIDC token#

If you enabled OIDC tokens in the web UI (under Settings → Request auth), you can pass a short-lived JWT from one of your trusted issuers as the request key, and your user ID with --user-id. For example, in a GitHub Actions workflow with id-token: write permission:

token="$(curl -sSf \
  -H "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
  "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=https://revaulter.example.com" | jq -r .value)"

revaulter-cli sign \
  --server https://revaulter.example.com \
  --request-key "$token" \
  --user-id "<your user ID>" \
  --key-label release-signing \
  --algorithm ES256 \
  --input dist/myapp

You can also pass the token in a file with --request-key-file. The CLI reads the file again for every request, so a long-running ssh-agent keeps working when the file is renewed in place, as with a Kubernetes projected service account token.

See Authenticating with OIDC tokens for how to set up the trusted issuers.

How it works#

When you run revaulter-cli encrypt, decrypt, or sign, the CLI:

1. Fetches the user’s public encryption keys from the server
2. Generates an ephemeral ECDH P-256 keypair and an ML-KEM-768 encapsulation
3. Encrypts the request payload end-to-end to the user’s public keys
4. Submits the encrypted request to the server
5. Long-polls for the result, authenticating with the result token the server returned in step 4
6. Decrypts the response envelope locally using its ephemeral private key

The server never has access to the plaintext request or response data.

Output#

By default, the CLI writes a JSON envelope to stdout, or to the file in --output. All binary values in it are base64url-encoded.

• encrypt writes the ciphertext with its nonce and tag, plus the algorithm and keyLabel used. Pass this JSON to decrypt --json as-is.
• decrypt writes the plaintext in value. --format raw writes the plaintext bytes instead, for piping into other commands or saving binary data.
• sign writes the signature, with the keyLabel, algorithm, and signingKeyId (the JWK thumbprint of the signing key). --format jws writes a compact JWS, and --format raw writes the 64-byte signature.

Exit codes#

• 0: the operation completed successfully
• Non-zero: the request was denied, canceled, or expired, or an error occurred (details are printed to stderr)