Documentation

CLI authentication

How browser approval, session storage, revocation, and Git credentials work.

The CLI uses a browser-approved session. It does not ask for your password and does not reuse a browser cookie.

Login flow

  1. upstream auth login creates a challenge with the Coline authentication authority.
  2. The CLI prints a one-time verification URL and polls the challenge for up to five minutes.
  3. You sign in, review the request, and approve or deny it in the browser.
  4. Approval returns the raw CLI session token once. The server stores only its hash.
  5. The CLI installs its Git credential helper and uses the session for authenticated API calls.

CLI sessions expire after 30 days and can be revoked from CLI session settings. Pending login requests can also be approved or denied there.

Local storage

On macOS, the CLI uses Keychain. On Linux, it uses Secret Service through secret-tool when available. Headless systems fall back to ~/.config/upstream-cli/auth.json with mode 0600.

Git credentials

The CLI session is not handed to ordinary Git processes. The credential helper exchanges it for a short-lived credential tied to one repository and the requested read or write operation. The server clamps that request to your actual role.

Sign out and revoke

upstream auth logout removes the local session material and the configured helper entry. Revoking a session in settings invalidates it server-side even if a copy remains on a machine.