From dee1b1e3bc109191775e12cb253974d9a533cf22 Mon Sep 17 00:00:00 2001
From: Johan Lundberg <lundberg@sunet.se>
Date: Wed, 18 Feb 2026 11:43:56 +0100
Subject: [PATCH] docs: update README with CLI commands and fix stale module
 name

---
 README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 44 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 984fed9..1afad76 100644
--- a/README.md
+++ b/README.md
@@ -34,10 +34,52 @@ uv sync --no-dev
 
 OIDC_OP_ISSUER=https://auth.example.com \
 OIDC_OP_SESSION_SECRET=$(python -c "import secrets; print(secrets.token_hex(32))") \
-  uv run uvicorn fastapi_oidc_op.app:create_app \
+  uv run uvicorn porchlight.app:create_app \
     --factory --host 0.0.0.0 --port 8000 --workers 4
 ```
 
+### Bootstrap the first admin user
+
+After starting the app for the first time, create an admin account:
+
+```bash
+OIDC_OP_ISSUER=https://auth.example.com \
+  uv run porchlight initial-admin admin
+```
+
+This prints a one-time registration URL. Open it in a browser to set up
+credentials (password or security key) for the admin user.
+
+### CLI commands
+
+Porchlight includes a CLI for administrative tasks. All commands read the same
+`OIDC_OP_*` environment variables as the server.
+
+**`porchlight create-invite <username>`** -- Generate a magic link registration
+URL for a new user.
+
+```bash
+uv run porchlight create-invite alice
+uv run porchlight create-invite alice --ttl 3600 --note "Onboarding"
+```
+
+| Option | Description |
+|---|---|
+| `--ttl SECONDS` | Link expiration (default: `OIDC_OP_INVITE_TTL`, 86400s) |
+| `--note TEXT` | Optional note stored with the link |
+
+**`porchlight initial-admin <username>`** -- Bootstrap the first admin user with
+a registration link.
+
+```bash
+uv run porchlight initial-admin admin
+uv run porchlight initial-admin admin --group admin --group superusers
+```
+
+| Option | Description |
+|---|---|
+| `--group TEXT` | Groups to assign (repeatable, default: `admin`, `users`) |
+
 ### Configuration
 
 All settings are read from environment variables with the `OIDC_OP_` prefix:
@@ -70,7 +112,7 @@ uv sync
 
 # Start the dev server with hot reload
 OIDC_OP_ISSUER=http://localhost:8000 OIDC_OP_DEBUG=true \
-  uv run uvicorn fastapi_oidc_op.app:create_app \
+  uv run uvicorn porchlight.app:create_app \
     --factory --host 127.0.0.1 --port 8000 --reload --reload-dir src
 ```