Authenticate via OAuth — you drive geekbot auth login yourself.
Do NOT tell the user to run anything in their shell. Do NOT ask for an
API key. The CLI's loopback flow only exposes a public authorize URL
(no secrets), and writes the resulting cli_* token to the user's OS
keychain on their own machine when the flow completes.
Procedure:
a. Start the login command in the background. Use Bash with
run_in_background: true so you can read the verification URL while
the CLI waits on its loopback listener. Always pass --no-browser —
you can't pick the user's browser for them, especially on WSL where
xdg-open would launch the Linux default rather than the browser
that holds the user's Geekbot dashboard session.
geekbot auth login --no-browser --ttl-days 30
b. Capture the authorize URL. Call BashOutput on the background
shell once, then again a second later if needed, until stderr
contains a line that starts with https:// and a URL pointing at
/v2/authorize?.... The CLI prints a block like:
Listening on http://127.0.0.1:<port>/callback for the OAuth callback…
Open this URL in a browser to sign in:
https://oauth.geekbot.com/v2/authorize?...&state=...&code_challenge=...
Only open it ONCE — the state is single-use.
c. Show the URL to the user, exactly once. Reply with something
like:
To finish signing in to Geekbot, open this URL in any browser
you're already logged into your dashboard with:
<URL>
Only open it once — the OAuth state is single-use, so a second
browser will fail.
d. Wait for the command to exit. Continue calling BashOutput
periodically until the background shell completes. Don't pre-empt
with a timeout shorter than the CLI's own (~5 min).
e. Parse the outcome:
- Exit 0 — stdout contains a JSON envelope of shape
{"ok": true, "data": {"authenticated": true, "method": "oauth_loopback", "username": ..., "email": ...}}.
Proceed to step 6.
- Non-zero exit — stdout/stderr contains an error envelope.
Common codes:
oauth_callback_timeout — user didn't click in time. Offer to
retry from step 5a.oauth_access_denied — user clicked "Cancel" at the IdP.oauth_state_mismatch / oauth_invalid_request — they opened
the URL twice; retry, remind them once is enough.oauth_invalid_client — the CLI's client_id isn't registered
on the auth server; this is an environment issue, not a user
one — report it and stop.
Fallback only — do NOT suggest unless OAuth login fails twice in a row
or the user explicitly asks for it. Long-lived dashboard API keys
still work via:
