Commands#
This page lists every command the Drawbridge CLI offers: config:validate, explain, render, revoke, smoke, keys:generate, keys:jwks and signer:map.
Run as php bin/drawbridge <command> (or vendor/bin/drawbridge when installed as a dependency).
The table is generated from the CLI itself, so the descriptions and options match the code you have installed.
The commands#
| Command | What it does |
|---|---|
bin/drawbridge explain |
Show what the gateway does with a request for a host and a path. |
bin/drawbridge render |
Render the Apache config and the Lua policy from the gateway config. |
bin/drawbridge revoke |
End the gateway sessions a person holds now, on every app host (the revocation list). |
bin/drawbridge smoke |
Check a running gateway without signing in: health, unknown hosts, each app's paths, the redirect URI, the app's clock and /metrics. |
bin/drawbridge config:validate |
Validate the gateway config file. |
bin/drawbridge keys:generate |
Generate an ES256 (P-256) assertion signing key pair. Refuses to overwrite. |
bin/drawbridge keys:jwks |
Write the JWKS key set file apps verify assertions with (public keys only, current then next). |
bin/drawbridge signer:map |
Run the assertion signer for Apache RewriteMap (reads stdin, writes stdout). |
bin/drawbridge explain#
Show what the gateway does with a request for a host and a path.
Usage: bin/drawbridge explain [-c|--config CONFIG] [--] <host> <path>
| Argument | Required | Meaning |
|---|---|---|
host |
yes | The app host. |
path |
yes | The request path, as sent (the query string is ignored). |
| Option | Meaning | Default |
|---|---|---|
-c, --config=VALUE |
Path to the config. Default: DRAWBRIDGE_CONFIG. | |
--silent |
Do not output any message |
bin/drawbridge render#
Render the Apache config and the Lua policy from the gateway config.
Usage: bin/drawbridge render [-c|--config CONFIG] [-o|--output-dir OUTPUT-DIR]
| Option | Meaning | Default |
|---|---|---|
-c, --config=VALUE |
Path to the config. Default: DRAWBRIDGE_CONFIG. | |
-o, --output-dir=VALUE |
Where to write apps.conf and policy.lua. | /tmp/drawbridge/generated |
--silent |
Do not output any message |
bin/drawbridge revoke#
End the gateway sessions a person holds now, on every app host (the revocation list).
Usage: bin/drawbridge revoke [-l|--list] [-f|--file FILE] [-c|--config CONFIG] [--] [<subject>...]
| Argument | Required | Meaning |
|---|---|---|
subject |
no | The person: the value of oidc.user_claim (the AccessID at WSU). One or more. |
| Option | Meaning | Default |
|---|---|---|
-l, --list |
Print the revocation list instead of changing it. | |
-f, --file=VALUE |
The revocation list. Default: DRAWBRIDGE_REVOCATION_FILE, else /tmp/drawbridge/revoked.txt. | |
-c, --config=VALUE |
Path to the config, for gateway.session_seconds (old entries are dropped). Default: DRAWBRIDGE_CONFIG. | |
--silent |
Do not output any message |
bin/drawbridge smoke#
Check a running gateway without signing in: health, unknown hosts, each app's paths, the redirect URI, the app's clock and /metrics.
Usage: bin/drawbridge smoke [-c|--config CONFIG] [--url URL] [--app APP] [--public-scheme PUBLIC-SCHEME] [--public-port PUBLIC-PORT] [--timeout TIMEOUT] [--format FORMAT]
| Option | Meaning | Default |
|---|---|---|
-c, --config=VALUE |
Path to the config. Default: DRAWBRIDGE_CONFIG. | |
--url=VALUE |
Where the gateway listens. Default: http://127.0.0.1:DRAWBRIDGE_PORT (inside the container). | |
--app=VALUE |
Check only this app id (repeatable). Default: every app. | |
--public-scheme=VALUE |
How browsers reach the gateway. Default: DRAWBRIDGE_PUBLIC_SCHEME, else https. | |
--public-port=VALUE |
The public port when it is not the scheme default. Default: DRAWBRIDGE_PUBLIC_PORT. | |
--timeout=VALUE |
Seconds to wait for each answer. | 10 |
--format=VALUE |
text or json. | text |
--silent |
Do not output any message |
bin/drawbridge config:validate#
Validate the gateway config file.
Usage: bin/drawbridge config:validate [-c|--config CONFIG]
| Option | Meaning | Default |
|---|---|---|
-c, --config=VALUE |
Path to the config (.yaml, .yml or .php). Default: DRAWBRIDGE_CONFIG. | |
--silent |
Do not output any message |
bin/drawbridge keys:generate#
Generate an ES256 (P-256) assertion signing key pair. Refuses to overwrite.
Usage: bin/drawbridge keys:generate [--private PRIVATE] [--public PUBLIC]
| Option | Meaning | Default |
|---|---|---|
--private=VALUE |
Where to write the private key. | |
--public=VALUE |
Where to write the public key. | |
--silent |
Do not output any message |
bin/drawbridge keys:jwks#
Write the JWKS key set file apps verify assertions with (public keys only, current then next).
Usage: bin/drawbridge keys:jwks [--key KEY] [--out OUT]
| Option | Meaning | Default |
|---|---|---|
--key=VALUE |
A public key as KID=FILE, for example drawbridge-2026-11=signing.pub. Repeat it: the current key first, then the next. | |
--out=VALUE |
Where to write the key set. Default: print it. | |
--silent |
Do not output any message |
bin/drawbridge signer:map#
Run the assertion signer for Apache RewriteMap (reads stdin, writes stdout).
Usage: bin/drawbridge signer:map [-c|--config CONFIG] [--key KEY] [--kid KID]
| Option | Meaning | Default |
|---|---|---|
-c, --config=VALUE |
Path to the config. Default: DRAWBRIDGE_CONFIG. | |
--key=VALUE |
The ES256 private key (PEM file). | |
--kid=VALUE |
The key ID put in each token header. | drawbridge-1 |
--silent |
Do not output any message |
Options every command accepts#
| Option | Meaning | Default |
|---|---|---|
-h, --help |
Display help for the given command. When no command is given display help for the list command | |
-q, --quiet |
Only errors are displayed. All other output is suppressed | |
| `-v | -vv | -vvv, --verbose` |
-V, --version |
Display this application version | |
--ansi |
Force (or disable --no-ansi) ANSI output | |
--no-ansi |
Negate the "--ansi" option | |
-n, --no-interaction |
Do not ask any interactive question |
The container entrypoint runs render itself, and signer:map is the long-running process behind Apache's prg: map, not for people.
revoke <subject>... ends every gateway session those people hold now, on every app host, and revoke --list prints the list. Run it where the gateway reads DRAWBRIDGE_REVOCATION_FILE, for example inside the gateway container; Signing out has the details.
smoke checks a running gateway from the outside without signing anyone in: /_drawbridge/up, a host that is not configured (403), and for each app a login path (a redirect to the provider with the redirect URI, client id and PKCE the config implies, and on an https host its state cookie marked Secure), an api path (a bare 401), a deny path (403), a public path (the app answers, and spoofed identity headers never reach it), the app host's clock against the gateway's (more than 10 s apart fails), a made-up callback (no session) and /metrics (gated; checked when DRAWBRIDGE_METRICS_TOKEN is set). It reads and changes nothing, so it is safe against a gateway that is serving people. The clock line compares the Date header of the app's answer on the public path with the gateway's own: SESAME allows 30 seconds of skew on a 60-second assertion, so more than 10 seconds apart fails. When the app sends no Date header, Apache adds the gateway's own and the line reads 0 s. Inside the gateway container every default is right: docker exec <gateway-container> /opt/drawbridge/bin/drawbridge smoke. Run it after every start, restart and rollback; First deployment does, on a trial host.
keys:generate and keys:jwks work together: the first makes a key pair, the second writes the key set file apps verify with, from the public halves (the current key first, then the next). Rotating the signing key walks through both.
Exit codes#
config:validate checks the config and prints every problem at once, then the provider settings (never the secret, only whether its variable is set); it exits 1 if any problem is found.
smoke exits 0 when no check failed (a skipped check is not a failure), 1 when one did, and 2 when it could not start (an unreadable config, an unknown --app, a bad option). --format=json prints the same result as one JSON document, for a test record.