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

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

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.

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