Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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")
  • --for is a whole number and a unit (30s, 15m, 6h, 7d), or always for a standing grant where the server allows it. Ask for the shortest time that does the job.
  • --reason is up to 280 characters. The approver reads it before deciding, labelled as reported by you, so say what the task is.
  • --host and --client change 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"
OutcomeMessageExit code
ApprovedApproved by Alice on Alice's phone. Grant grt_..., for 15 minutes.0
DeniedDenied by Alice on Alice's phone.3
Nobody decided in time4
CancelledCancelled.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

OptionWhat it does
--env NAME=fieldSets the environment variable NAME from field. Repeatable. Once you use it, only the fields you name are passed
--file NAME=fieldPuts 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 fieldGives the field to the command on its standard input, without a trailing newline. One field only. Linux and Windows (from 0.5.1)
--prefix PPuts 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_* and BOUNCER_* (bouncer exec --help lists 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

  • --json prints 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.
  • bouncer never 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.

This manual covers Bouncer 0.5.7. Built from source commit cdd3b5958d5be0b33e865b1b56b770f6bccffaf7 (workspace version 0.5.7+34).