Manual for Bouncer 0.5.7. Chapters state version and distribution limits. Source cdd3b59, site build 20 November 2026. Your server or app may run an earlier version.
On this page
Use the CLI
This page shows the everyday bouncer commands. The resource IDs and field names are examples; bouncer resources shows yours. The full option list is in the CLI reference.
There is no dedicated command that prints a secret. bouncer exec delivers values to a child command through its environment, standard input or a Linux in-memory file. That command can still print or log the values, so check its output with a fake secret before you use a real one (Patterns for workloads and agents).
See what you may ask for
bouncer resources
It lists each resource's ID, name, kind, field names, the durations it offers, whether it accepts new values (WRITE), and anything open now: your pending request or the grant exec would use. It never shows a value. bouncer resources --json gives the same for scripts.
Ask for access
bouncer request prod-db-password --for 15m --reason "Run the March billing migration"
Expected result: the request ID, then two lines about it:
req_01jbx3k9m2p4q6r8s0t1v3w5y7
Asked for Production database password (prod-db-password) for 15 minutes. The approver has until 2026-11-15T06:43:32Z to decide.
Wait for the decision with: bouncer wait req_01jbx3k9m2p4q6r8s0t1v3w5y7
The request ID alone goes to standard output, and the other two lines go to standard error. So in a script, capture the ID and use it in the commands below:
REQ=$(bouncer request prod-db-password --for 15m --reason "Run the March billing migration")
--foris a whole number and a unit (30s,15m,6h,7d), oralwaysfor a standing grant where the server allows it. Ask for the shortest time that does the job.--reasonis up to 280 characters. The approver reads it before deciding, labelled as reported by you, so say what the task is.--hostand--clientchange the machine name and program name shown to the approver. They are also labelled as reported, never verified.
Wait for the decision
bouncer wait "$REQ"
| Outcome | Message | Exit code |
|---|---|---|
| Approved | Approved by Alice on Alice's phone. Grant grt_..., for 15 minutes. | 0 |
| Denied | Denied by Alice on Alice's phone. | 3 |
| Nobody decided in time | 4 | |
| Cancelled | Cancelled. | 5 |
Or ask and wait in one go: bouncer request prod-db-password --for 15m --reason "..." --wait.
wait keeps going through short network outages or a server restart, for up to 5 minutes.
Run a command with the secret
bouncer exec prod-db-password -- ./migrate.sh
exec finds your active grant, fetches a short-lived OpenBao token, reads the secret, and runs the command with the values in its environment. It names each variable after the field, in capitals: the field password becomes PASSWORD. Before running the command it tells you which variables it set, never their values:
bouncer: Set from kv/apps/billing/db-password: PASSWORD.
The command's exit code becomes bouncer's. The token expires by itself. Values copied by the command, and sessions it opens, can outlive it.
Choose how the command gets the value
| Option | What it does |
|---|---|
--env NAME=field | Sets the environment variable NAME from field. Repeatable. Once you use it, only the fields you name are passed |
--file NAME=field | Puts the field in a private in-memory file (never on disk, mode 0600, and locked so it cannot be changed) and sets NAME to its path, such as /dev/fd/3. Linux only |
--stdin field | Gives the field to the command on its standard input, without a trailing newline. One field only. Linux and Windows (from 0.5.1) |
--prefix P | Puts P in front of every default variable name |
Examples, with a fake secret whose field is api_key:
bouncer exec demo --env DEMO_KEY=api_key -- sh -c 'test -n "$DEMO_KEY" && echo set'
bouncer exec demo --file KEYFILE=api_key -- sh -c 'test -s "$KEYFILE" && echo readable'
bouncer exec demo --stdin api_key -- sh -c 'v=$(cat); test -n "$v" && echo "read from stdin"'
bouncer: Set from kv/apps/demo: DEMO_KEY.
set
bouncer: Set from kv/apps/demo: KEYFILE (a file).
readable
bouncer: Set from kv/apps/demo: standard input.
read from stdin
Use --stdin or --file for tools that won't read the environment. docker login --password-stdin is a common case:
bouncer exec registry --stdin password -- docker login registry.example.com --username ci --password-stdin
Which fields become variables
Field names come from whoever wrote the secret, so by default exec only sets a variable whose name looks like a secret's: KEY, TOKEN, SECRET, PASSWORD or PASSPHRASE, or ending in _KEY, _TOKEN, _SECRET, _PASSWORD, _PASSPHRASE or _ID. Other fields (url, username) are skipped, with a notice. Name them yourself to use them:
bouncer exec prod-db-password --env DB_HOST=host --env DB_USER=username --env DB_PASSWORD=password -- ./migrate.sh
exec refuses to run, and runs nothing, if:
- a default variable name is protected: a name that changes how programs run or where they connect, such as
PATH,LD_PRELOAD,GIT_*,*_PROXY,VAULT_*andBOUNCER_*(bouncer exec --helplists them all); - the variable is already set;
- two fields would get the same name.
To set a protected name on purpose, name it with --env and add --allow-env-name NAME.
No grant yet
With --reason, exec files a request itself and waits for approval, then runs:
bouncer exec prod-db-password --for 15m --reason "Run the March billing migration" -- ./migrate.sh
Without --for, it asks for the resource's first duration and says so. With --no-request (or without --reason) it never asks, and exits 8 when there's no active grant. Use that from cron and CI.
List and end your grants
bouncer grants # active grants
bouncer grants --all # including ended ones
GRANT=$(bouncer grants --resource prod-db-password --id-only | head -n 1)
bouncer revoke "$GRANT"
Expected result of revoke:
Grant grt_01jbx3n4q6s8t0v2w4x6y8z0a2 is revoked as of 2026-11-15T06:28:34Z. No new tokens can be issued for it.
Token iss_01jbx3q6s8t0v2w4x6y8z0a2b4, due to expire 2026-11-15T06:33:21Z: revoked at OpenBao
A secret value that was already read can't be recalled. If it was read, rotate it.
End a grant as soon as the job is done. It exits 10 if OpenBao didn't confirm every token's revoke; the grant is still ended.
Withdraw a request
bouncer cancel "$REQ"
The approvers' notifications are withdrawn.
Check on requests
bouncer status # your recent requests
bouncer status "$REQ" # one in full
Save a new value
For a resource that accepts writes (WRITE yes in bouncer resources), for example after you rotate an API key at its provider:
printf %s "$NEW_KEY" | bouncer put deploy-token --field token --reason "Rotated after the March incident"
bouncer put deploy-token --field token --file ./new-token.txt --reason "Rotated after the March incident"
put files a request that names the fields, never the values, waits for approval, then sends the values once. Other fields in the secret are kept. With several --fields, the input is a JSON object with one string per field. It exits 0 once saved, 3 if denied, 4 if the request expired.
SSH to a host
For an SSH host resource, bouncer ssh makes a new key, has Bouncer get it a short-lived certificate, and connects:
bouncer ssh web1-deploy --to web1.example.com --reason "Restart the web service"
bouncer ssh web1-deploy --to web1.example.com -- systemctl status nginx
The private key stays on your machine and is deleted afterwards. A revoke stops new logins on a host only once that host has fetched and installed Bouncer's revocation list and its sshd reads it through RevokedKeys. The host's timer tries every 15 seconds, but Bouncer can't confirm delivery, so bouncer revoke says NOT confirmed for each certificate. With --json, each one has "outcome": "unknown" and "pending": "krl_delivery". The certificate also expires at its own end time. An SSH session that's already open stays open. Follow Keep SSH revocations up to date to install and monitor the host's KRL pull service.
Not verified for this page: put and ssh weren't part of our test run. Their behaviour is from bouncer put --help, bouncer ssh --help and the CLI's tests.
Scripting
--jsonprints the server's answers exactly as they came. On an error, it still prints one JSON document on standard output and the explanation on standard error.bouncernever prompts and never reads the terminal, so it behaves the same in a shell, cron, systemd, CI or an agent.- Every failure has a specific exit code: see Exit codes and errors.
How this was checked
The messages on this page are checked against the CLI source. A historical 0.5.0 run with fake secrets has no retained transcript in this manual's evidence. The fake-data operator tests later reran exec reading a stored value and exec --no-request exiting 8 after a revoke. Resource names and IDs use the examples from this guide.