CLI: auth-aware first-run onboarding so a fresh install reaches first success without a cryptic failure

[MervinPraison]

Summary

A brand-new user who installs PraisonAI and runs praisonai (or praisonai run "…") with no configured credentials is dropped straight into an agent run that only fails when the first LLM call is attempted — with no guidance toward the existing onboarding wizard. The install → first-run path is the primary CLI battleground, and today it has a silent first-failure for unconfigured users despite all the machinery to fix it already existing.

Current behaviour

• Running praisonai with no arguments launches the interactive TUI on a hardcoded default model (AsyncTUIConfig(model="gpt-4o-mini", …) in src/praisonai/praisonai/cli/app.py). If no OPENAI_API_KEY / stored credential is present, the failure only appears at the first model call.
• A capable onboarding wizard already exists — praisonai setup (cli/commands/setup.py, idempotent) — and credential storage/resolution exists (auth command, llm/credentials.py, ~/.praison/), but nothing detects an unconfigured environment and routes the user there. There is no first-run / has_credentials check anywhere in cli/app.py, __main__.py, or cli/commands/run.py.
• doctor/env/diag commands exist but the user has to know to run them; they are not part of the first-run path.
• Net effect: the very first interaction for an unconfigured user is an error with no actionable next step — the worst first impression for the CLI-first flow.

Desired behaviour

• On a run where no usable credential/model can be resolved, detect this before the first LLM call and guide the user: offer to launch setup (or print the exact one-liner: provider choice + key + default model), then continue.
• Make this non-intrusive and respect non-interactive/CI contexts: in --quiet/non-tty/non-interactive mode, emit a single clear, actionable error (which key/command is missing) and exit non-zero — never hang on a prompt.
• First successful setup writes sensible defaults to ~/.praison/config.toml so subsequent runs are zero-prompt.
• A returning, already-configured user sees no change (no extra prompts, no latency).

Layer placement

• Primary layer: wrapper (src/praisonai/praisonai/)
• Why not core: onboarding, credential detection and CLI prompting are wrapper concerns; the core SDK has no CLI and must not gain interactive UX or credential discovery.
• Why not tools: this is not an agent-callable integration.
• Why not plugins: it is not a lifecycle hook/guardrail/policy on agent execution; it is install/first-run UX that runs before any agent.
• Secondary touch (optional): a small reusable credentials.is_configured() helper in the wrapper llm/ package, shared by run, TUI and doctor.
• 3-way surface (CLI + YAML + Python): no — this is inherently a CLI/first-run UX concern (the Python and YAML entry points assume the developer already supplies keys/config).

Proposed approach

1. Add credentials.is_configured(model=…) (wrapper llm/) returning whether a credential resolves for the selected/default model.
2. In the no-arg path (cli/app.py) and at the top of run (cli/commands/run.py), call it; if unconfigured and interactive, prompt to launch the existing setup wizard; if non-interactive, print one actionable error and exit non-zero.
3. Reuse cli/commands/setup.py unchanged (already idempotent) — this is wiring, not a new wizard.
4. Gate entirely behind "no usable credential" so configured users and explicit --model/env flows are untouched.

Resolution sketch

llm/credentials.py            # is_configured(model) helper
cli/app.py                    # no-arg path: detect → offer setup (tty) / error (non-tty)
cli/commands/run.py           # pre-run credential gate, same behaviour
cli/commands/setup.py         # reused as-is (idempotent)

Severity

Medium — does not affect configured users, but it is the first thing every new user hits, and the fix reuses existing components.

Validation

• Fresh environment, no keys: praisonai and praisonai run "hi" guide to setup (interactive) or exit non-zero with a precise message (non-interactive) — never an opaque mid-run stack trace.
• After setup, real agentic test: agent.start("real task") / praisonai run "real task" calls the LLM and succeeds with zero further prompts.
• Already-configured environment: behaviour and startup latency unchanged (regression check).

[praisonai-triage-agent]

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

---

✅ Completed auth-aware first-run onboarding implementation

Summary

Successfully implemented auth-aware first-run onboarding to ensure new users get proper guidance instead of cryptic failures when no API keys are configured.

Changes Made

1. Added is_configured() helper (llm/credentials.py):

   • Checks both environment variables and stored credentials
   • Supports model-specific credential validation
   • Falls back through multiple detection methods

2. Added credential check in CLI entry points:

   • cli/app.py: Checks before launching TUI on no-arg invocation
   • cli/commands/run.py: Checks before executing run commands
   • Both offer to launch setup wizard in interactive mode
   • Non-interactive/CI contexts get clear actionable error messages

3. Preserved existing behavior:

   • Configured users see no change
   • No added latency for existing workflows
   • Setup wizard remains unchanged (idempotent)

Testing & Validation

• ✅ Python syntax validation passed
• ✅ Import tests successful
• ✅ is_configured() correctly detects missing credentials
• ✅ All changes are in wrapper layer (not core SDK)

Pull Request

🔗 PR #2126: fix: add auth-aware first-run onboarding to prevent cryptic failures
|