From browser login back to localhost: Authdog CLI OAuth
How Authdog CLI combines hosted sign-in, a loopback callback, and a one-time grant to authenticate a native terminal application.
Authdog Engineering
Native command-line tools need browser-grade authentication without asking users to paste long-lived secrets into a terminal. Authdog CLI solves that with a hosted sign-in flow and a temporary loopback listener bound to 127.0.0.1.
The result feels simple: enter /login, complete sign-in in a browser, and return to the CLI already authenticated.
Start with a local callback
The CLI chooses an available local port and starts a short-lived HTTP listener. It then opens the hosted Authdog sign-in page with callback state that identifies this login attempt.
After authentication, the browser is redirected to:
http://127.0.0.1:<port>/oauth/callbackBinding to the loopback interface keeps the listener local to the device. The callback accepts a one-time, 64-character hexadecimal grant rather than exposing access or refresh tokens in the browser URL.
Redeem once, then close
The CLI sends the grant to Authdog for redemption. A successful response returns access and refresh tokens to the native process, which persists the session for later authenticated requests.
The callback listener has an eight-minute deadline. Grant redemption retries for up to two minutes to tolerate short propagation or network delays. Once the exchange succeeds, the browser displays a branded completion page and the local listener exits.
Separate browser trust from CLI trust
This flow gives each surface a narrow job:
- Browser handles interactive authentication.
- Loopback callback receives an ephemeral grant.
- Authdog server redeems that grant once.
- CLI stores the resulting session and calls authenticated APIs.
No password passes through the terminal. No reusable token needs to be copied from a web page.
Local session security
On Unix systems, Authdog creates the credential file with mode 0600, restricting it to the current user. /status shows where credentials live and previews session state without printing complete tokens. /logout deletes the local credential file.
The beta stores tokens in local JSON rather than an operating-system keychain, and it does not yet expose refresh as a user workflow. Those are important constraints for users evaluating the current release.
Loopback OAuth gives the CLI a practical native sign-in experience now while preserving a clear path toward stronger platform-specific credential storage later.