Uh oh!
There was an error while loading. Please reload this page.
fix(docs): correct nonexistent CLI flags and document --url as required - #88
Merged
Conversation
Verified every `--flag` in docs/ against the flag list the built binary actually registers. Five were wrong, all in copy-pasteable blocks: - sso-guide: `authorizer serve` -> `authorizer` (no such subcommand) - sso-guide: `--port` -> `--http-port` - sso-guide: `--sender-email` -> `--smtp-sender-email` - databases: `--couchbase-bucket-ram-quota` -> `--couchbase-ram-quota` - v1-to-v2: `--skip-tls-verification` -> `--smtp-skip-tls-verification` Also drops `--include-permissions-in-token` and `--authorization-log-all-checks` from server-config: both were removed when OpenFGA was embedded, and were still shown in a runnable command. The sso-guide block failed twice before reaching config validation.
#764 made --url mandatory — the server refuses to start without it — but the docs were never swept. 22 of 24 pages carrying a runnable authorizer command omitted it, so every documented quickstart, deployment guide and SDK setup produced a server that will not boot on 2.4.0. That includes getting-started, the first command a new user runs. Adds --url to every block that actually starts a server, matching each page's context (localhost for local/docker examples, the platform URL for Railway/Render/Koyeb/Heroku/Fly, the Ingress host for Kubernetes), and adds AUTHORIZER_URL to the required-variable tables that feed those commands. Left alone: flag fragments that illustrate one setting, the v1 "before" example, and `authorizer mcp`, which takes --mcp-authorizer-url and does not require --url (verified against a build). Also states the difference between the three similarly-named settings, which had no single home and was the likely source of the omission: --url this server's own address (server flag, required) --allowed-origins the apps allowed to talk to it (server flag) authorizerURL the client's pointer back at the server (SDK option) There is no --authorizer-url server flag; X-Authorizer-URL is the legacy header --url replaces. The security.md entry is now the single canonical explanation, with server-config linking to it rather than restating it — all three copies still described --url as optional and "recommended for production". Records the requirement as a 2.4.0 breaking change in the migration guide, alongside --encryption-key and the delegated-agent deny default. Drive-by, same class of bug: the Kubernetes manifest referenced $(ENCRYPTION_KEY) in args with no matching env entry, so it never expanded.
✅ Deploy Preview for authorizerdev-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This was referenced Aug 14, 2026
--url is required as of 2.4.0 and is consulted before any header, so --mcp-authorizer-url is ignored whenever --url is set. The stdio example passed both with DIFFERENT values, which is exactly the trap: the mcp-authorizer-url value was inert and looked configured. Removed from the runnable blocks, marked deprecated in the flag table.
Still accepted so existing setups keep starting, but ignored: it only stamped an x-authorizer-url header, and --url is consulted before any header. Replaced with --url in the runnable blocks and the flag table. --mcp-bearer without --url is now refused at startup.
Uh oh!
There was an error while loading. Please reload this page.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Two related classes of bug, both found by checking every
--flagindocs/against the flag list a build ofmainactually registers.1. Flags that do not exist
Five appeared in copy-pasteable blocks. The SSO quickstart failed twice before reaching config validation:
authorizer serveauthorizer(no such subcommand)--port--http-port--sender-email--smtp-sender-email--couchbase-bucket-ram-quota--couchbase-ram-quota--skip-tls-verification--smtp-skip-tls-verificationAlso drops
--include-permissions-in-tokenand--authorization-log-all-checksfrom server-config — both were removed when OpenFGA was embedded, and one was still shown inside a runnable command.2.
--urlis required in 2.4.0 and the docs never said so#764 made
--urlmandatory. Every page carrying a runnableauthorizercommand omitted it — 22 of 24 by the first count, and a second detector keyed on--database-typerather than./authorizerfound more indocker.md,fly-io,helm-chartandkubernetes(~40 blocks total), so every documented quickstart, deployment guide and SDK setup produces a server that will not boot — includinggetting-started, the first command a new user runs.The precedent is visible in the repo: when
--encryption-keybecame required, every page was swept.--urlnever got the same sweep.Adds
--urlto every block that actually starts a server, matched to context — localhost for local/Docker examples, the platform URL for Railway/Render/Koyeb/Heroku/Fly, the Ingress host for Kubernetes — plusAUTHORIZER_URLrows in the required-variable tables those commands read from.Deliberately left alone: flag fragments illustrating one setting (the
databases.mdper-engine snippets), the v1 "before" example in the migration guide, andauthorizer mcp, which takes--mcp-authorizer-urland does not require--url— verified by running it.--urlvs--allowed-originsvsauthorizerURLThese had no single home, which is the likely source of the omission. Now stated once in security.md:
--url--allowed-originsauthorizerURLThere is no
--authorizer-urlserver flag, andX-Authorizer-URLis the legacy header--urlreplaces.Deduplication
Three pages independently described
--url, and all three still called it optional and "recommended for production". security.md is now the single canonical explanation; server-config links to it instead of restating it.Recorded as a 2.4.0 breaking change in the migration guide, alongside
--encryption-keyand the delegated-agent deny default — the guide had no 2.3.x→2.4.0 section at all.Drive-by
Same class of bug: the Kubernetes manifest referenced
$(ENCRYPTION_KEY)inargswith no matchingenventry, so it never expanded.Verification
--flagindocs/diffed againstauthorizer --helpandauthorizer mcp --helpfrom a build ofmain; zero invalid flags remain in command blocks (residual matches are CSS custom properties, curl and kubectl flags)npm run buildclean, zero broken-link or broken-anchor warningsRefs authorizerdev/authorizer#764, authorizerdev/authorizer#766, authorizerdev/authorizer#767