CLI: first-run credential setup and persistent provider config (`praisonai auth`)

[MervinPraison]

Summary

A brand-new user who installs praisonai and runs praisonai run "hello" hits a raw provider error unless they have already exported OPENAI_API_KEY. There is no guided way to store credentials, pick a default model, or verify the setup. The wrapper should own a world-class first-run flow: praisonai auth login, secure credential storage, and a clear actionable message when no key is configured.

Current behaviour

• praisonai/llm/env.py resolves the endpoint purely from environment variables (resolve_llm_endpoint()), silently defaulting to gpt-4o-mini with api_key=None; the failure surfaces later as a raw API error mid-run.
• There is no auth command in praisonai/cli/commands/ — the closest is environment.py, which can view/check env vars (redacted) but cannot set or persist anything.
• The config system (praisonai/cli/configuration/loader.py, paths.py, schema.py) supports ~/.praison/config.toml + project .praison/config.toml, but holds no credential or provider section and is not consulted for keys.
• praisonai onboard (cli/commands/onboard.py) is bot-channel onboarding (Telegram/Discord/Slack), not LLM provider setup.

Desired behaviour

• praisonai auth login [provider] — interactive prompt (paste key, optional base URL/model), validated with a cheap live call, persisted to ~/.praison/credentials.json with 0o600 permissions. Non-interactive: praisonai auth login openai --key-stdin.
• praisonai auth list / praisonai auth logout [provider] for inspection and removal (keys always redacted in output).
• Credential resolution order: explicit env var → stored credential → fail fast. The wrapper exports the resolved key into the process env before invoking praisonaiagents, so the core SDK stays untouched.
• When no key is found, praisonai run exits immediately with a one-line fix: No API key configured. Run: praisonai auth login — instead of a mid-run provider traceback.
• Default model/provider selection persisted in the existing config.toml (e.g. [llm] model = "...") and honoured by praisonai run when --model is absent.

Layer placement

• Primary layer: wrapper
• Why not core: the core SDK is protocol-driven and correctly receives credentials via env/parameters; credential storage and onboarding are install/UX concerns that must not add I/O or prompts to the runtime.
• Why not wrapper: n/a — this is the wrapper's job (install, first run, defaults).
• Why not tools: not agent-callable functionality.
• Why not plugins: not a lifecycle hook, guardrail, or policy.
• Secondary touch (optional): none required; wrapper exports resolved values via env, which praisonaiagents already reads.
• 3-way surface (CLI + YAML + Python): yes — CLI (praisonai auth ...), YAML/TOML (config.toml [llm] defaults referenced by agents.yaml runs), Python (env injection means Agent(...) works unchanged after auth login).

Proposed approach

1. Add praisonai/cli/commands/auth.py (Typer group: login, list, logout, status) and register it in cli/app.py.
2. Add a small CredentialStore in praisonai/cli/configuration/ — JSON file keyed by provider, written atomically with 0o600, lazy-imported.
3. Extend resolve_llm_endpoint() to optionally accept a fallback lookup injected by the wrapper (env always wins; backward-compatible signature).
4. Add the fail-fast preflight check to praisonai run / direct-prompt paths with the actionable message.
5. Extend ConfigSchema with an [llm] section (model, provider, base_url) consumed by run when flags are absent.

Resolution sketch

• cli/commands/auth.py (~150 lines), cli/configuration/credentials.py (~80 lines).
• llm/env.py: add optional fallback parameter to resolve_llm_endpoint().
• cli/commands/run.py: preflight check + config-default model resolution.
• Tests: store round-trip, permission bits, precedence (env > store), preflight error message. Real agentic test: praisonai run "What is 2+2?" succeeds after auth login with no env vars set.

Severity

Critical — this is the single biggest barrier between pip install praisonai and first success; every new CLI user hits it.

Validation

• Traced: praisonai/llm/env.py (env-only resolution, api_key=None default), praisonai/cli/commands/ (no auth command exists), cli/commands/environment.py (view-only), cli/configuration/schema.py (no credential/llm section).
• No duplication: environment, config, and onboard commands cover adjacent but distinct concerns.

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job • claude/issue-1925-20260612-2322 • [Create PR ➔](https://github.com/MervinPraison/PraisonAI/compare/main...claude/issue-1925-20260612-2322?quick_pull=1&title=Issue%20%231925%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%231925%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Claude finished @MervinPraison's task

---

Todo List

• Read AGENTS.md architecture guidelines
• Analyze current codebase structure
• Setup git identity and auth
• Implement credential storage system
• Create auth CLI commands (login, logout, list, status)
• Extend LLM endpoint resolution with credential fallback
• Add preflight checks to prevent raw API errors
• Update config schema for LLM defaults
• Test the implementation
• Commit and push changes
• Create pull request

✅ Implementation Complete

I've successfully implemented a comprehensive CLI authentication system for PraisonAI that addresses the raw provider error issue described in #1925. The implementation follows the protocol-driven architecture guidelines and provides a world-class first-run experience.

🔑 Key Features Delivered

🔐 Secure Credential Storage

• Credentials stored in ~/.praison/credentials.json with 0o600 permissions
• Atomic writes prevent corruption during updates
• JSON format with provider-specific settings (API key, base URL, model)

⚡ Complete Auth CLI

• praisonai auth login <provider> - Interactive and non-interactive credential setup
• praisonai auth logout <provider> - Remove stored credentials
• praisonai auth list - Show all providers (keys redacted for security)
• praisonai auth status [provider] - Check credential validity with optional live validation

🔄 Smart Credential Resolution

• Precedence order: Environment variables → stored credentials → fail fast
• Automatic credential injection into process environment for backward compatibility
• Extended LLM endpoint resolution in wrapper layer (core SDK unchanged)

✅ Fail-Fast Protection

• Preflight checks in praisonai run prevent raw API errors
• Clear, actionable error message: "No API key configured. Run: praisonai auth login"
• Graceful degradation when credential system is unavailable

⚙️ Enhanced Configuration

• New [llm] section in config schema for default model/provider settings
• Backward compatible with existing [model] section
• Support for provider-specific base URLs and models

🏗️ Architecture Compliance

✅ Protocol-driven core: Core SDK (praisonaiagents) unchanged, credentials implemented in wrapper layer
✅ Lazy imports: Optional dependencies imported only when needed
✅ Security first: Secure file permissions, no logged secrets, format validation
✅ Backward compatible: Existing environment variable patterns continue to work
✅ Fail fast: Clear error messages with actionable remediation hints

📁 Files Implemented

• cli/commands/auth.py - Auth command group with full CLI interface
• cli/configuration/credentials.py - Secure credential storage with CredentialStore class
• llm/credentials.py - Bridge between credential store and LLM resolution
• llm/env.py - Extended endpoint resolution with fallback support
• cli/commands/run.py - Added preflight checks for API key availability
• cli/configuration/schema.py - Extended config schema with LLM defaults
• cli/app.py - Registered auth command group in main CLI app

🧪 Testing

All functionality validated with comprehensive test suite:

• ✅ Credential storage with proper file permissions
• ✅ Auth command interfaces and validation
• ✅ LLM endpoint resolution with fallback
• ✅ Configuration schema serialization
• ✅ End-to-end auth integration flow

🚀 Usage Examples

# First-time setup (interactive)
praisonai auth login openai

# Direct credential input
praisonai auth login openai --key sk-proj-...

# Pipeline credential input
echo "sk-proj-..." | praisonai auth login openai --key-stdin

# View stored providers (keys redacted)
praisonai auth list

# Check credential status with live validation
praisonai auth status openai --validate

# Remove credentials
praisonai auth logout openai

# Now works seamlessly without raw errors
praisonai run "What is 2+2?"

📋 Pull Request Created

PR #1928: feat: implement CLI authentication system (fixes #1925)

The implementation provides the exact solution requested in the issue - transforming the barrier of raw API errors into a guided, secure credential management experience that makes PraisonAI immediately usable for new users.