CLI reference
This page is the --help output of the bouncer, bouncer-admin, bouncer-mcp and bouncer-server binaries built from the source this site was built from, exactly as they print it. This reference covers Bouncer 0.5.7. Exit code 16 and bouncer-server --check-config do not appear in the 0.5.6 binaries' help. Your server may run another version. On Windows, bouncer also has key save (Saving your key on Windows); self-update and exec --file are Linux only.
bouncer-admin runs only on the Bouncer server's machine. With the compose kit, run it as docker compose exec bouncer bouncer-admin ....
Numbers such as (D22) in the help text point to the project's internal decision log, which isn't published. You don't need it: the text around each number says what the command does.
Two notes on the help text. A command run with exec can still print, log or save the values it gets, and exec doesn't redact its output (Patterns for workloads and agents). For SSH, the 15-second timer is how often hosts try to fetch the revocation list, not confirmed delivery (SSH to a host).
bouncer
Ask for access to a secret, wait for approval on your phone, and use it
Usage: bouncer [OPTIONS] <COMMAND>
Commands:
resources List the resources you may ask for: their fields, durations, and your pending requests and grants
request Ask for access to a resource. Prints the request ID
status Show one request, or your recent ones
wait Wait for the decision on a request. Exits 0 only if it's approved
exec Run a command with a resource's secret in its environment
grants List your grants (active ones, unless you give --all)
revoke End one of your grants now, and revoke its tokens
cancel Withdraw one of your pending requests
put Save a new secret value, once it's approved
ssh Log in to an SSH host resource with a short-lived certificate
help Print this message or the help of the given subcommand(s)
Options:
--json
Print the server's answers as JSON, exactly as they came, for scripts
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
Connection (optional, see Configuration in bouncer --help):
--server <URL>
The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server
[env: BOUNCER_URL]
--key-file <PATH>
A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key
[env: BOUNCER_KEY_FILE]
Configuration:
BOUNCER_URL The Bouncer server's address (or --server). Or put it in
$XDG_CONFIG_HOME/bouncer/server (~/.config/bouncer/server).
BOUNCER_KEY The requester key itself. Or put it in a file: --key-file,
BOUNCER_KEY_FILE, or $XDG_CONFIG_HOME/bouncer/key
(~/.config/bouncer/key). The file must be private (chmod 600).
The key is never a command-line argument, and never printed.
BOUNCER_CA_FILE Extra CA certificates (PEM) to trust, for Bouncer and OpenBao
Durations are a whole number and a unit, as in the server's config: 30s, 15m,
6h or 7d, or always. A grant lasts from 1 minute to 365 days, or always.
With --json, each command prints the server's answer exactly as it came
(contract bouncer.v1); resources adds pending_request and active_grant to
each resource. An error from the server is printed the same way, as its
problem+json body, and explained on stderr.
Exit codes:
0 Done. For wait, request --wait and exec: the request was approved
1 Something went wrong (the server couldn't be reached, failed, or sent
something this version can't read)
2 The command line was wrong
3 The request was denied
4 The request expired without a decision
5 The request was cancelled or superseded
6 The server refused (key not accepted, not allowed, not found, invalid input)
7 Configuration problem (no server address, no key, a key file others
can read, plain http to another machine, an admin socket that can't
be opened, or resource_not_provisioned: the operator must apply and
check the role kit before retrying; no immediate retries)
8 No active grant for the resource
9 The deadline passed in a request state this version doesn't know
10 Revoked, but not every issued token was confirmed revoked
11 revoke --all wasn't confirmed
12 The server is running, but its vault (OpenBao) is sealed. Not a refusal:
the operator must unseal it
13 The server is running, but can't reach its vault (OpenBao)
14 The server is running, but its vault refused the server's own login.
Not a refusal of your key: the operator must fix the server's login
15 The proxy in front of the server got no answer from it (HTTP 502, 503
or 504 with no Bouncer error): the server is down or restarting
16 The server is running, but can't reach its database (PostgreSQL)
126 exec: the command couldn't be started
127 exec: the command wasn't found
Once exec has started the command, the exit code is the command's own.
bouncer resources
List the resources you may ask for: their fields, durations, and your pending requests and grants
Usage: bouncer resources [OPTIONS]
Options:
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
Connection (optional, see Configuration in bouncer --help):
--server <URL> The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server [env: BOUNCER_URL]
--key-file <PATH> A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key [env: BOUNCER_KEY_FILE]
bouncer request
Ask for access to a resource. Prints the request ID
Usage: bouncer request [OPTIONS] --for <DURATION> --reason <REASON> <RESOURCE>
Arguments:
<RESOURCE> The resource's ID in the server's config, such as demo
Options:
--for <DURATION> How long you need it: 15m, 6h, 7d, always, ...
--reason <REASON> Why you need it, in your own words (up to 280 characters). The approver sees it
--json Print the server's answers as JSON, exactly as they came, for scripts
--wait Wait for the decision too, as bouncer wait does
--client <NAME> The program asking, shown to the approver as reported by you [default: bouncer CLI]
--host <NAME> This machine's name, shown to the approver as reported by you [default: the host name]
-h, --help Print help
Connection (optional, see Configuration in bouncer --help):
--server <URL> The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server [env: BOUNCER_URL]
--key-file <PATH> A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key [env: BOUNCER_KEY_FILE]
bouncer status
Show one request, or your recent ones
Usage: bouncer status [OPTIONS] [REQUEST]
Arguments:
[REQUEST] A request ID (req_…). Without one, lists your recent requests
Options:
--limit <LIMIT> How many recent requests to list [default: 20]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
Connection (optional, see Configuration in bouncer --help):
--server <URL> The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server [env: BOUNCER_URL]
--key-file <PATH> A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key [env: BOUNCER_KEY_FILE]
bouncer wait
Wait for the decision on a request. Exits 0 only if it's approved
Usage: bouncer wait [OPTIONS] <REQUEST>
Arguments:
<REQUEST> The request ID (req_…)
Options:
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
Connection (optional, see Configuration in bouncer --help):
--server <URL> The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server [env: BOUNCER_URL]
--key-file <PATH> A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key [env: BOUNCER_KEY_FILE]
bouncer exec
Run a command with a resource's secret in its environment.
1. Finds your active grant for the resource. If there isn't one, files a
request with --reason and waits for the decision, or stops if you gave
--no-request. --for defaults to the resource's first duration (bouncer
resources lists them).
2. Fetches a short-lived OpenBao token for the grant (5 minutes by default),
unwrapping it at OpenBao if the server sends it wrapped.
3. Reads each of the grant's KV paths from OpenBao with that token, and
names a variable after each field: the field's name in upper case, with
anything other than letters and digits as _ (api_key becomes API_KEY).
Field names come from whoever wrote the secret, so by default only a name
that looks like a secret's is set: KEY, TOKEN, SECRET, PASSWORD or
PASSPHRASE, or one ending in _KEY, _TOKEN, _SECRET, _PASSWORD, _PASSPHRASE
or _ID. Any other field (url, cc, pager) is skipped, and a notice on stderr
names it. Another notice names each variable that was set, never its
value: a GITHUB_TOKEN or AWS_ACCESS_KEY_ID set from a field overrides
what gh or aws keep in their own config. exec stops before running
anything if a default name is protected (VAULT_TOKEN, BOUNCER_KEY,
SSH_KEY, NPM_TOKEN, DOPPLER_TOKEN and the other names below), is already
set, or two fields would get the same name. --env NAME=field picks the
fields and names them yourself; then only those are set. Use
NAME=mount/path:field when two paths have the same field. An --env may
replace an inherited variable, but a protected name also needs
--allow-env-name NAME.
On Linux, --file NAME=field puts a field in a private in-memory file
(mode 0600, sealed, never on disk) and sets NAME to its path, /dev/fd/N.
--stdin field gives a field to the command on its standard input. Once
you give any --env, --file or --stdin, only the fields you name are
passed on. A secret is never put in the command's arguments.
4. Runs the command, with BOUNCER_KEY taken out of its environment. Nothing
is revoked afterwards: the token expires by itself.
The values are read once, at the start. A long-running command keeps those
values, but the token itself expires within minutes, so the command can't
read anything new from OpenBao later.
bouncer never prints, logs or saves the secret. The exit code is the
command's own; bouncer --help lists bouncer's own codes.
Protected names: BOUNCER_*, VAULT_*, BAO_*, DOPPLER_*, INFISICAL_*, BWS_*, GIT_*, SSH_*, SSL_*, OPENSSL_*, CURL_*, XDG_*, BASH*, LESS*, TERMINFO*, PYTHON*, NODE_*, NPM_*, YARN_*, PERL*, RUBY*, GEM_*, BUNDLE_*, PIP_*, UV_*, LUA_*, ERL_*, DOTNET_*, CORECLR_*, CARGO_*, RUST*, CGO_*, DOCKER_*, KRB5*, LD_*, DYLD_*, MALLOC_*, *_PROXY, *FLAGS, *PAGER, *EDITOR, *_OPTS, *_OPTIONS, *_RSH, *_PUBLIC_KEY, PATH, HOME, SHELL, USER, LOGNAME, TMPDIR, TMP, TEMP, IFS, ENV, PS0, PS1, PS2, PS3, PS4, PROMPT_COMMAND, SHELLOPTS, HISTFILE, INPUTRC, ZDOTDIR, CC, CXX, CPP, LD, AR, MAKE, MAKEFILES, VISUAL, BROWSER, VIMINIT, GVIMINIT, EXINIT, NO_PROXY, REQUESTS_CA_BUNDLE, SSLKEYLOGFILE, NETRC, WGETRC, HOSTALIASES, LOCALDOMAIN, KUBECONFIG, GNUPGHOME, GPG_KEY, OP_SERVICE_ACCOUNT_TOKEN, OP_CONNECT_TOKEN, GCONV_PATH, GLIBC_TUNABLES, LOCPATH, NLSPATH, CLASSPATH, PHPRC, PHP_INI_SCAN_DIR, GOFLAGS, GOPROXY, GOSUMDB, GONOSUMDB, GONOPROXY, GOPRIVATE, GOINSECURE, GOTOOLCHAIN, GOENV, GOROOT, in any case.
Usage: bouncer exec [OPTIONS] <RESOURCE> -- <COMMAND>...
Arguments:
<RESOURCE>
The resource's ID in the server's config, such as demo
<COMMAND>...
The command to run, after --
Options:
--for <DURATION>
If there's no active grant: how long to ask for [default: the resource's first duration, as bouncer resources shows]
--reason <REASON>
If there's no active grant: why you need it
--json
Print the server's answers as JSON, exactly as they came, for scripts
--no-request
Don't ask for access: fail if there's no active grant
--env <NAME=FIELD>
Set NAME from a field: NAME=field, or NAME=mount/path:field. Repeatable
--file <NAME=FIELD>
Put a field in a private in-memory file and set NAME to its path (/dev/fd/N): NAME=field, or NAME=mount/path:field. Repeatable. Linux only
--stdin <FIELD>
Give a field to the command on its standard input: field, or mount/path:field. Linux and Windows
--prefix <PREFIX>
Put PREFIX in front of every default variable name
--allow-env-name <NAME>
Let an --env or --file set NAME even though it's a protected name (BOUNCER_*, VAULT_*, *_PROXY, GIT_*, CC, PATH, ...). Repeatable
--client <NAME>
The program asking, shown to the approver as reported by you [default: bouncer CLI]
--host <NAME>
This machine's name, shown to the approver as reported by you [default: the host name]
-h, --help
Print help (see a summary with '-h')
Connection (optional, see Configuration in bouncer --help):
--server <URL>
The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server
[env: BOUNCER_URL]
--key-file <PATH>
A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key
[env: BOUNCER_KEY_FILE]
bouncer grants
List your grants (active ones, unless you give --all)
Usage: bouncer grants [OPTIONS]
Options:
--all List every grant, not just the active ones
--limit <LIMIT> How many to list [default: 50]
--json Print the server's answers as JSON, exactly as they came, for scripts
--resource <RESOURCE> Only the grants for this resource
--id-only Print only the grant IDs, one per line, newest first: GRANT=$(bouncer grants --resource demo --id-only | head -n 1)
-h, --help Print help
Connection (optional, see Configuration in bouncer --help):
--server <URL> The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server [env: BOUNCER_URL]
--key-file <PATH> A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key [env: BOUNCER_KEY_FILE]
bouncer revoke
End one of your grants now, and revoke its tokens
Usage: bouncer revoke [OPTIONS] <GRANT>
Arguments:
<GRANT> The grant ID (grt_…)
Options:
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
Connection (optional, see Configuration in bouncer --help):
--server <URL> The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server [env: BOUNCER_URL]
--key-file <PATH> A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key [env: BOUNCER_KEY_FILE]
bouncer cancel
Withdraw one of your pending requests
Usage: bouncer cancel [OPTIONS] <REQUEST>
Arguments:
<REQUEST> The request ID (req_…)
Options:
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
Connection (optional, see Configuration in bouncer --help):
--server <URL> The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server [env: BOUNCER_URL]
--key-file <PATH> A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key [env: BOUNCER_KEY_FILE]
bouncer put
Save a new secret value into a resource, once it's approved.
Files a store request naming the fields (never the values), waits for the
approver to approve it on their phone or PC, then sends the values to the
Bouncer server, which saves them into the resource's secret in OpenBao. Other
fields in that secret are kept. Each approval saves once.
The value is never a command-line argument, so it stays out of your shell
history and the process list. Pipe it in, or give --file:
printf %s "$NEW_KEY" | bouncer put example-api-key --field api_key --reason "Rotated"
bouncer put example-api-key --field api_key --file ./new-key.txt --reason "Rotated"
With one --field, the whole input is the value (one trailing newline is
dropped). With several, the input is a JSON object with one string per field:
{"api_key": "...", "region": "..."}.
The resource must allow writes (allow_write in the server's config). Exits 0
once saved, 3 if denied, 4 if the request expired.
Usage: bouncer put [OPTIONS] --field <NAME> --reason <REASON> <RESOURCE>
Arguments:
<RESOURCE>
The resource's ID in the server's config, such as example-api-key
Options:
--field <NAME>
The field to save, such as api_key. Repeat for several fields
--file <PATH>
Read the value from this file instead of standard input
--json
Print the server's answers as JSON, exactly as they came, for scripts
--reason <REASON>
Why you're saving it, in your own words (up to 280 characters). The approver sees it
--for <DURATION>
How long, once approved, the values may still be sent: 1m to 1h
[default: 5m]
--client <NAME>
The program asking, shown to the approver as reported by you [default: bouncer CLI]
--host <NAME>
This machine's name, shown to the approver as reported by you [default: the host name]
-h, --help
Print help (see a summary with '-h')
Connection (optional, see Configuration in bouncer --help):
--server <URL>
The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server
[env: BOUNCER_URL]
--key-file <PATH>
A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key
[env: BOUNCER_KEY_FILE]
bouncer ssh
Log in to an SSH host resource with a short-lived certificate.
1. Finds your active grant for the resource, or files a request (--reason,
and --for or the resource's first duration) and waits for the decision,
as exec does.
2. Makes a new ed25519 key with ssh-keygen, in a private temporary folder.
3. Sends its public half to Bouncer, which has OpenBao sign a certificate
for it: one account (the resource's principal), at most the resource's
credential TTL (5 minutes by default), never past the grant's end, and
usually bound to the address the server saw you call from.
4. Runs ssh with that key and certificate only (no agent, no other keys,
no passwords) as <principal>@<the --to host>, then deletes the key.
The private key never leaves this machine. A revoke stops new logins once
the host has fetched Bouncer's revocation list, normally within 15 seconds;
a session that is already open stays open. The exit code is ssh's own.
Usage: bouncer ssh [OPTIONS] --to <HOST> <RESOURCE> [-- <COMMAND>...]
Arguments:
<RESOURCE>
The SSH host resource's ID in the server's config, such as web1
[COMMAND]...
A command to run on the host instead of a shell, after --
Options:
--to <HOST>
The host to connect to: a name or address ssh understands
--port <PORT>
The port, if it isn't 22
--for <DURATION>
If there's no active grant: how long to ask for [default: the resource's first duration, as bouncer resources shows]
--json
Print the server's answers as JSON, exactly as they came, for scripts
--reason <REASON>
If there's no active grant: why you need it
--no-request
Don't ask for access: fail if there's no active grant
--ssh-option <KEY=VALUE>
Pass an option to ssh, as ssh -o does, such as UserKnownHostsFile=~/.ssh/work_hosts. Repeatable
--client <NAME>
The program asking, shown to the approver as reported by you [default: bouncer CLI]
--host <NAME>
This machine's name, shown to the approver as reported by you [default: the host name]
-h, --help
Print help (see a summary with '-h')
Connection (optional, see Configuration in bouncer --help):
--server <URL>
The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server
[env: BOUNCER_URL]
--key-file <PATH>
A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key
[env: BOUNCER_KEY_FILE]
bouncer self-update
Update a user-local install of bouncer and bouncer-mcp (from install.sh) to the newest signed release. It does nothing unless you run it: no background checks.
The release manifest must be signed by the key built into this bouncer, list a build for this machine, and be newer than this version. Each binary must match the manifest's SHA-256. The old binaries are kept beside the new ones as .bouncer.old and .bouncer-mcp.old.
It refuses while another bouncer or bouncer-mcp from this install is running, and for binaries a package manager owns (/usr/bin, or anything dpkg or rpm knows): update those with apt or dnf.
Usage: bouncer self-update [OPTIONS]
Options:
--check
Only say whether an update is available
--prerelease
Follow the prerelease channel instead of stable
--allow-downgrade
Allow installing an older version than this one
--rollback
Put back the binaries the last update replaced
--feed <URL>
The update feed's base URL (https, or http to this machine)
[env: BOUNCER_UPDATE_FEED=]
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
bouncer-admin
Pair devices, manage requester keys and pull the kill switch, on the Bouncer server's own machine
Usage: bouncer-admin [OPTIONS] <COMMAND>
Commands:
device Pair, list and revoke phones and PCs
requester Create requesters (people, agents and hosts), rotate their keys, disable them
revoke The kill switch: end every grant, cancel every pending request, revoke every token
config The policy config file
downstream Credentials issued by other systems (a Proxmox API token, say), which Bouncer can't revoke there
grant Standing (Always) grants: re-confirm their review
log The approval log
personal Personal credentials (D63): suspend Always approved, freeze, reassign
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH>
The server's admin socket
[env: BOUNCER_ADMIN_SOCKET=]
--json
Print the server's answers as JSON, exactly as they came, for scripts
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
bouncer-admin runs on the Bouncer server's own machine. It talks to the
server over a local Unix socket, never the network: --socket, else
BOUNCER_ADMIN_SOCKET, else /run/bouncer/admin.sock. The socket's file
permissions decide who is the admin.
With --json, each command prints the server's answer exactly as it came
(contract bouncer.v1).
Exit codes:
0 Done. For wait, request --wait and exec: the request was approved
1 Something went wrong (the server couldn't be reached, failed, or sent
something this version can't read)
2 The command line was wrong
3 The request was denied
4 The request expired without a decision
5 The request was cancelled or superseded
6 The server refused (key not accepted, not allowed, not found, invalid input)
7 Configuration problem (no server address, no key, a key file others
can read, plain http to another machine, an admin socket that can't
be opened, or resource_not_provisioned: the operator must apply and
check the role kit before retrying; no immediate retries)
8 No active grant for the resource
9 The deadline passed in a request state this version doesn't know
10 Revoked, but not every issued token was confirmed revoked
11 revoke --all wasn't confirmed
12 The server is running, but its vault (OpenBao) is sealed. Not a refusal:
the operator must unseal it
13 The server is running, but can't reach its vault (OpenBao)
14 The server is running, but its vault refused the server's own login.
Not a refusal of your key: the operator must fix the server's login
15 The proxy in front of the server got no answer from it (HTTP 502, 503
or 504 with no Bouncer error): the server is down or restarting
16 The server is running, but can't reach its database (PostgreSQL)
126 exec: the command couldn't be started
127 exec: the command wasn't found
Once exec has started the command, the exit code is the command's own.
bouncer-admin device
Pair, list and revoke phones and PCs
Usage: bouncer-admin device [OPTIONS] <COMMAND>
Commands:
pair Make a one-time pairing code, shown as a QR code to scan with the app
list List every device, active and revoked
revoke Revoke a device: it can no longer sign in, decide or see anything. Its Always grants end; its finite grants stay until they end
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin device pair
Make a one-time pairing code, shown as a QR code to scan with the app
Usage: bouncer-admin device pair [OPTIONS] --person <PERSON>
Options:
--person <PERSON> The person the device pairs as: their ID in the config file
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
--ttl <TTL> How long the code works: 1m to 30m [default: 5m]
-h, --help Print help
bouncer-admin device list
List every device, active and revoked
Usage: bouncer-admin device list [OPTIONS]
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin device revoke
Revoke a device: it can no longer sign in, decide or see anything. Its Always grants end; its finite grants stay until they end
Usage: bouncer-admin device revoke [OPTIONS] <DEVICE>
Arguments:
<DEVICE> The device ID (dev_…)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin requester
Create requesters (people, agents and hosts), rotate their keys, disable them
Usage: bouncer-admin requester [OPTIONS] <COMMAND>
Commands:
add Create a requester and its first key. The key is shown once
list List every requester
rotate-key Issue a new key and stop the old one at once. The new key is shown once. Its standing grants are suspended
disable Disable a requester: its key stops working, its pending requests are cancelled and its grants revoked [alias: revoke]
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin requester add
Create a requester and its first key. The key is shown once
Usage: bouncer-admin requester add [OPTIONS] --kind <KIND> <NAME>
Arguments:
<NAME> A name: lower-case letters, digits, dots, dashes and underscores, such as build-agent
Options:
--kind <KIND> What it is [possible values: agent, host, human]
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
--owner <OWNER> The person it belongs to, by their ID in the config file. Their requests are labelled as theirs (D18)
-h, --help Print help
bouncer-admin requester list
List every requester
Usage: bouncer-admin requester list [OPTIONS]
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin requester rotate-key
Issue a new key and stop the old one at once. The new key is shown once. Its standing grants are suspended
Usage: bouncer-admin requester rotate-key [OPTIONS] <REQUESTER>
Arguments:
<REQUESTER> The requester's ID (rqr_…) or name
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin requester disable
Disable a requester: its key stops working, its pending requests are cancelled and its grants revoked
Usage: bouncer-admin requester disable [OPTIONS] <REQUESTER>
Arguments:
<REQUESTER> The requester's ID (rqr_…) or name
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin revoke
The kill switch: end every grant, cancel every pending request, revoke every token
Usage: bouncer-admin revoke [OPTIONS] --all
Options:
--all Everything. Required: there's no partial kill switch
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-y, --yes Don't ask for confirmation
-h, --help Print help
bouncer-admin config
The policy config file
Usage: bouncer-admin config [OPTIONS] <COMMAND>
Commands:
reload Load the config file again. An invalid one is refused and the old one stays
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin config reload
Load the config file again. An invalid one is refused and the old one stays
Usage: bouncer-admin config reload [OPTIONS]
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin downstream
Credentials issued by other systems (a Proxmox API token, say), which Bouncer can't revoke there
Usage: bouncer-admin downstream [OPTIONS] <COMMAND>
Commands:
list List each one, and whether it needs rotating at its system
rotated Record that you rotated one at its system and updated its secret
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin downstream list
List each one, and whether it needs rotating at its system
Usage: bouncer-admin downstream list [OPTIONS]
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin downstream rotated
Record that you rotated one at its system and updated its secret
Usage: bouncer-admin downstream rotated [OPTIONS] <RESOURCE>
Arguments:
<RESOURCE> The resource ID in the config file
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin grant
Standing (Always) grants: re-confirm their review
Usage: bouncer-admin grant [OPTIONS] <COMMAND>
Commands:
review Re-confirm a standing grant, so it isn't suspended when its review is due (D22)
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin grant review
Re-confirm a standing grant, so it isn't suspended when its review is due (D22)
Usage: bouncer-admin grant review [OPTIONS] <GRANT>
Arguments:
<GRANT> The grant ID (grt_…)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin log
The approval log
Usage: bouncer-admin log [OPTIONS] <COMMAND>
Commands:
export Write every entry, oldest first, as JSON lines, for an archive, syslog or a SIEM. Never holds a secret
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin log export
Write every entry, oldest first, as JSON lines, for an archive, syslog or a SIEM. Never holds a secret
Usage: bouncer-admin log export [OPTIONS]
Options:
--since <SINCE> Only entries from this time on: a time such as 2026-11-01T00:00:00Z, or how long ago, such as 24h or 7d
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
--until <UNTIL> Only entries before this time, in the same forms
--after <AFTER> Carry on after this cursor, from the end of an earlier export
--cursor-file <FILE> Start after the cursor in this file, if it exists, and save the new one there when done. For a job that ships only what's new each run
--out <FILE> Write to this new file (mode 0600) instead of stdout. An existing file isn't overwritten
-h, --help Print help
bouncer-admin personal
Personal credentials (D63): suspend Always approved, freeze, reassign
Usage: bouncer-admin personal [OPTIONS] <COMMAND>
Commands:
suspend Suspend Always approved: requests wait for approval until the owner signs it again (D22)
freeze Freeze: nobody can use it until it's reassigned; its grants end
reassign Give a frozen credential, or one whose owner left the config file, to another person
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin personal suspend
Suspend Always approved: requests wait for approval until the owner signs it again (D22)
Usage: bouncer-admin personal suspend [OPTIONS] [CREDENTIAL]
Arguments:
[CREDENTIAL] The personal credential ID (pc-…)
Options:
--namespace <NAMESPACE> Every personal credential in this namespace instead
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin personal freeze
Freeze: nobody can use it until it's reassigned; its grants end
Usage: bouncer-admin personal freeze [OPTIONS] [CREDENTIAL]
Arguments:
[CREDENTIAL] The personal credential ID (pc-…)
Options:
--namespace <NAMESPACE> Every personal credential in this namespace instead
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin personal reassign
Give a frozen credential, or one whose owner left the config file, to another person
Usage: bouncer-admin personal reassign [OPTIONS] --owner <OWNER> <CREDENTIAL>
Arguments:
<CREDENTIAL> The personal credential ID (pc-…)
Options:
--owner <OWNER> The new owner, a person ID from the config file. Always approved stays suspended until they sign it
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-mcp
bouncer-mcp: the Bouncer MCP server. It lets an AI agent ask a human for
access to a secret, wait for the human to approve it on their phone, and then
read the secret. Agents can never approve anything.
An MCP client starts it and talks to it over stdin and stdout. For Claude Code:
claude mcp add bouncer \
--env BOUNCER_URL=https://bouncer.example.net \
--env BOUNCER_KEY_FILE=$HOME/.config/bouncer/agent-key \
-- /path/to/bouncer-mcp
Usage:
bouncer-mcp Serve MCP over stdin and stdout
bouncer-mcp --check Check the settings and the key against the server, then exit
bouncer-mcp --version Print the version
bouncer-mcp --help Print this help
Settings (environment variables):
BOUNCER_URL The Bouncer server's address: https://, or http:// to this
machine only
BOUNCER_KEY_FILE Required. The file holding the agent's own requester key.
It must be private (chmod 600). The CLI's default key file
is never used, and the key itself is never read from the
environment.
BOUNCER_CA_FILE Extra CA certificates (PEM) to trust, for Bouncer and OpenBao
The key must belong to an agent requester. At start-up, and with --check,
bouncer-mcp asks the server who the key belongs to, and refuses to run with a
person's or a host's key. Make an agent requester with:
bouncer-admin requester add <name> --kind agent --owner <person>
Logs go to stderr. The key, the OpenBao tokens and secret values never appear
in them.
bouncer-server
The server's own options. The compose kit sets them for you (--trusted-proxy 127.0.0.1 in compose.yaml, and --config and --listen from the entrypoint).
usage: bouncer-server --config <file> [--listen <address:port>] [--admin-socket <path>] [--release-mode wrapped|direct] [--trusted-proxy <ip>]... [--fake-backend]
--config <file> the policy config file (required)
--check-config read-only OpenBao preflight for this candidate file;
print each resource's result and exit (no database)
--listen <addr:port> the public API's TCP address (default 127.0.0.1:8080)
--admin-socket <path> the admin API's Unix socket (default: $BOUNCER_ADMIN_SOCKET,
else /run/bouncer/admin.sock)
--release-mode <mode> how tokens are handed over: wrapped (default) or direct
--trusted-proxy <ip> a proxy whose X-Forwarded-For is believed, for the caller's
address; repeat for more. None by default. Behind
tailscale serve, use 127.0.0.1
--fake-backend use a built-in fake instead of OpenBao, for trying the
server out. Its tokens are fake and open nothing.
Without --fake-backend, the server issues tokens through OpenBao, using the
config's openbao section and the role kit's role ID and secret ID files.
The database URL comes from DATABASE_URL. Push is set in the config file's
push section.