Implement OAuth-based token generation for seamless CLI login

[weppos]

Description

Today, authenticating the DNSimple CLI requires the user to manually generate an API token in the DNSimple web UI and then paste it into the CLI (via dnsimple login or equivalent). This is friction-heavy: it forces context switching between terminal and browser, it exposes long-lived tokens to copy/paste, and it is inconsistent with the login experience offered by most modern developer CLIs (gh auth login, stripe login, vercel login, gcloud auth login, etc.), which use an OAuth-style browser handoff.

We want the CLI login to be as seamless as possible: the user runs a single command, a browser opens, they approve the request in DNSimple, and the CLI ends up with a working token, with no manual copy/paste of credentials.

DNSimple's API supports OAuth 2.0 (see https://developer.dnsimple.com/v2/oauth/), so the building blocks are in place at the API level. What needs investigation is whether the DNSimple application side exposes everything a public CLI client needs to implement a modern OAuth flow (PKCE, loopback redirect, or device authorization), and which flow gives the best UX and security for a local CLI.

Expected Behavior or Outcome

• Running dnsimple login (or equivalent) starts an OAuth flow without the user having to pre-generate a token in the web UI.
• The CLI opens the user's browser to the DNSimple authorization page; after approval, control returns to the CLI automatically.
• On success, the CLI stores a usable credential locally and subsequent commands are authenticated without further prompts.
• If the browser cannot be opened (e.g., headless/SSH session), the CLI falls back to a flow that works without a local browser (e.g., device code flow, or manual token entry as today).
• Errors (denied consent, timeout, network failure) produce clear, actionable messages and leave no partial/broken credentials on disk.

Acceptance Criteria

• Review of the dnsimple-app requirements, and extension plan if needed.
• dnsimple login performs the OAuth flow end-to-end and yields a working credential with no manual token copy/paste on the golden path.
• A documented fallback exists for environments without a browser (headless servers, SSH sessions, CI), which may include the existing path.

Resources/References

• DNSimple OAuth docs: https://developer.dnsimple.com/v2/oauth/
• Prior art worth reviewing:
  • GitHub CLI gh auth login (device code + browser)
  • Stripe CLI stripe login (browser handoff with pairing code)
  • Vercel CLI vercel login (email + magic link / OAuth)
  • gcloud auth login (loopback redirect with PKCE)
• RFC 8252, OAuth 2.0 for Native Apps (loopback redirect guidance)
• RFC 8628, OAuth 2.0 Device Authorization Grant
• RFC 7636, Proof Key for Code Exchange (PKCE)

Notes

This issue intentionally scopes both the investigation and the implementation. The investigation output should be recorded (in a comment or linked doc) before implementation begins, so that any required DNSimple app-side changes can be raised as separate tickets against the appropriate repo and unblocked in parallel.

Out of scope for this issue: token refresh UX beyond what the chosen flow requires, SSO/SAML-specific flows, and any changes to how tokens are authorized on the server side beyond what the OAuth flow itself needs.