Praison AI

CLI OAuth Login

Sign in to LLM providers using browser-based OAuth or device-code flow — tokens auto-refresh in the background

Sign in to any supported provider with a single command. OAuth tokens refresh automatically, so you never have to re-paste an API key.

python
from praisonaiagents import Agent

agent = Agent(
    name="Researcher",
    instructions="Answer questions using Gemini.",
    model="gemini/gemini-1.5-pro",
)

agent.start("Summarise the RFC 8628 device-code flow in three bullets.")

The user runs praisonai auth login; OAuth tokens are stored and refreshed so agents call the provider without pasting API keys.

Diagram

praisonai auth login –method oauth

Yes

No

Yes

No

Yes

No

👤 User

💻 praisonai auth login github
–method oauth –client-id …

🔎 Provider in
OAUTH_PROVIDERS?

🔑 client_id set?

📥 Endpoint overrides
via flags?

🌐 Device / PKCE flow

💬 Info: pass –client-id

❌ Error: not OAuth-capable

💾 ~/.praisonai/credentials.json

🔑 API-key fallback

🤖 Agent auto-refreshes token

Quick Start

  1. Log in with browser (recommended)
    bash
    praisonai auth login github --method oauth --client-id <your-github-oauth-app-client-id>

    GitHub uses the device-code flow (no local browser callback listener): a short code prints, a browser tab opens to the verification page, and credentials are stored once you approve.

  2. Log in on a headless server (device code)

    On a machine without a browser, add --no-browser to get a device code:

    bash
    praisonai auth login github --method oauth --client-id <your-github-oauth-app-client-id> --no-browser
    To sign in, visit https://github.com/login/device and enter code: ABCD-1234

    Enter the code on any device, then come back — the CLI detects approval automatically.

  3. Force API-key login

    If you prefer to manage keys manually, use --method apikey:

    bash
    praisonai auth login openai --method apikey

    You’ll be prompted for the key interactively (hidden input), or pipe it:

    bash
    echo "sk-..." | praisonai auth login openai --method apikey --key-stdin
  4. Check auth status and expiry
    bash
    praisonai auth list
    Provider    Method    Expiry
----------  --------  -------
github      oauth     2h 14m
openai      apikey    (n/a)
    bash
    praisonai auth status github

    Shows whether the current token is valid and when it expires.

How It Works

Diagram
AgentCredential StoreOAuth Providerpraisonai auth loginUserAgentCredential StoreOAuth Providerpraisonai auth loginUserLater…auth login github –method oauth –client-id …Request device code (RFC 8628)device_code, user_code, verification_uri“Visit <url>, enter code: XXXX-YYYY”Approve in browseraccess_token + refresh_tokenstore_oauth_credential(provider, tokens)✅ Saved to ~/.praisonai/credentials.jsonload credentials for githubaccess_token (auto-refreshed if needed)API call with token

Auth Methods

MethodFlagWhen to use
auto(default)Uses OAuth if provider supports it and no --key is given; falls back to API-key prompt
oauth--method oauthAlways use OAuth, even if a key is available
apikey--method apikeyAlways use API key, skip OAuth discovery

Provider Compatibility

ProviderAPI-key loginOAuth login
github✅✅ (requires --client-id)
google / gemini✅✅ (requires --client-id)
azure✅✅ (requires --client-id)
anthropic✅❌
openai✅❌
Custom / self-hosted✅✅ (supply endpoints via flags)

Use praisonai auth login <provider> --method auto — the CLI auto-detects whether OAuth is supported. Registry providers need a --client-id; without one, auto prints how to switch to OAuth and falls back to the API-key prompt.

Token Storage

Credentials are stored at ~/.praisonai/credentials.json (or the path returned by praisonai paths). Legacy ~/.praison/credentials.json is read as a fallback and migrated on the next write — no re-login required. Each provider gets its own entry containing:

  • Auth method (apikey or oauth)
  • Token value (API key or access token)
  • Refresh token (OAuth only)
  • Expiry timestamp (OAuth only)

Tokens are refreshed transparently before each agent run when they are within the refresh window.

Best Practices

Use API keys in CI — not OAuth

OAuth device-code flows require human interaction. In automated pipelines (CI/CD, cron jobs), always use API keys via environment variables:

bash
ANTHROPIC_API_KEY=sk-ant-... praisonai run task.yaml

Or store them with --method apikey and a --key-stdin pipe from your secrets manager.

Log out when rotating credentials

When you rotate an API key or revoke an OAuth token:

bash
praisonai auth logout github
praisonai auth login github --method oauth --client-id <your-github-oauth-app-client-id>

This removes the old credential and re-runs the login flow.

Pin the model when using OAuth

OAuth credentials are provider-scoped. If a provider has multiple models, pin the default model at login time:

bash
praisonai auth login gemini --method oauth --client-id <your-google-oauth-client-id> --model gemini-1.5-pro
Supply your OAuth app client id

Registry providers ship endpoints but no client_id. Register your OAuth app with the provider (GitHub App / Google OAuth client for TVs / Azure AD app), then pass its id with --client-id. Until a first-party PraisonAI app is provisioned, you use your own.

bash
praisonai auth login github --method oauth --client-id <your-github-oauth-app-client-id>
Sign in to a self-hosted gateway

For a provider outside the registry, supply the OAuth endpoints directly with CLI flags:

bash
praisonai auth login my-gateway --method oauth \
  --client-id cli \
  --device-authorization-url https://gateway.example.com/oauth/device \
  --token-url https://gateway.example.com/oauth/token \
  --scope "read write"

Related

Security Environment Variables

How to pass credentials safely via environment variables

 Default Model Selection

How the CLI picks the right model when multiple providers are logged in

 MCP OAuth

MCP tools have their own OAuth flow, separate from CLI provider sign-in