First-run Onboarding

Auto-detects missing credentials and routes new users into the setup wizard

PraisonAI leads you to a verified, working agent in as few keystrokes as possible — auto-detecting any provider key you already have or a locally-running model (e.g. Ollama) reachable on the machine, validating the one you enter, and smoke-testing before it hands back the prompt.

praisonai --init is now safe to run before setup — if no provider is configured it prints provider guidance and exits cleanly rather than throwing a stack trace. Either order works for onboarding.

from praisonaiagents import Agent

agent = Agent(name="onboarding-agent", instructions="Guide new users through setup.")
agent.start("Walk me through setting up PraisonAI for the first time.")

The user launches PraisonAI without API keys; the CLI uses a reachable local model if one is running, otherwise offers the setup wizard instead of failing on the first model call.

All four LLM-bound entrypoints — praisonai (bare), praisonai run, praisonai code, and praisonai chat — route their first-run check through the same shared helper, so a keyless newcomer is offered the wizard (or a clean hint) from any first command.

Onboarding Flow

Quick Start

1. Run praisonai without any setup

   praisonai

   If no cloud credentials are configured and no local model is reachable, you’ll see:

   No API key configured.
   Would you like to run the setup wizard now? [Y/n]:

   Type Y (or press Enter) to launch the setup wizard.

2. Complete setup once

   The setup wizard asks for your provider and API key, then stores the credential securely:

   praisonai setup
   # Choose from a catalogue-driven menu: OpenAI, Anthropic, Google, Ollama, Groq,
   # OpenRouter, Mistral, DeepSeek, xAI, … (curated first, Custom last)
   # Enter your API key when prompted (a "Get your key" hint prints first)

   Credentials are stored in ~/.praisonai/credentials.json (permissions 0600). Legacy ~/.praison/credentials.json is still read as a fallback and migrated automatically on the next write — no re-login required.

3. Re-run — no prompts after the first time

   praisonai "What is 2+2?"
   # Runs immediately — no credential prompt

Wizard flow (post-#2680)

The wizard moves through three stages: auto-detect, validate, and smoke-test.

1. Auto-detect a key you already have

   If a *_API_KEY is already exported, the first prompt is a confirmation — not a numeric menu:

   Detected ANTHROPIC_API_KEY in your environment.
   Use Anthropic (claude-sonnet-4-20250514)? [Y/n]:

   Answer n to fall through to the full provider menu. The pre-selection surface is no longer four keys — the wizard auto-detects any catalogued credential env var (the full 14-row table), including Together (TOGETHER_API_KEY / TOGETHERAI_API_KEY) and Fireworks (FIREWORKS_API_KEY / FIREWORKS_AI_API_KEY) aliases. The provider menu only appears when no key is detected, and is catalogue-driven — it lists every provider ModelCatalogue knows about (Groq, OpenRouter, Mistral, DeepSeek, xAI, …), curated ones first and custom last.

   Just having a catalogued key set is enough — no wizard, no --model:

   Mistral

   # Only MISTRAL_API_KEY set in the environment — no wizard, no --model needed.
   from praisonaiagents import Agent
   
   agent = Agent(name="assistant", instructions="Answer briefly.")
   agent.start("Say hello in one line.")
   # Uses mistral/mistral-large-latest automatically.

   DeepSeek

   # Only DEEPSEEK_API_KEY set in the environment.
   from praisonaiagents import Agent
   
   agent = Agent(name="assistant", instructions="Answer briefly.")
   agent.start("Say hello in one line.")
   # Uses deepseek/deepseek-chat automatically.

   Fireworks

   # Only FIREWORKS_AI_API_KEY set — the alias is honoured.
   from praisonaiagents import Agent
   
   agent = Agent(name="assistant", instructions="Answer briefly.")
   agent.start("Say hello in one line.")
   # Uses fireworks_ai/accounts/fireworks/models/llama-v3p3-70b-instruct automatically.

2. Validate the key before it persists

   Entered keys run through the same validate_api_key() check as praisonai auth login. A bad key re-prompts instead of silently writing a broken credential:

   2. Enter your OpenAI API key:
   Enter API key (hidden):
   Invalid API key for OpenAI: OpenAI keys start with "sk-"
   Try again? [Y/n]: y
   Enter API key (hidden):

   After up to three attempts the wizard proceeds with the last entry so you’re never stuck in a loop.

3. Smoke-test before handing back the prompt

   After the config is written, the wizard runs one live call and prints the reply:

   Verifying your setup...
   ✅ Verified — your agent is working!
   Hello! How can I help you today?

   A failed smoke test is a warning, not an error — your config is already saved, so you can run praisonai doctor to diagnose the key or model.

How It Works

praisonai (bare), praisonai run, praisonai code, and praisonai chat all perform the same credential check before doing any work — each one delegates to the shared ensure_configured_or_onboard() helper.

Shared onboarding helper

Every entrypoint funnels its first-run check through one choke point, ensure_configured_or_onboard(*, model, interactive) in praisonai_code/llm/credentials.py. It returns the model unchanged when already configured, adopts a reachable local endpoint (with a one-line stderr notice) when keyless and no explicit model is set, exits 1 with Run: praisonai setup when keyless and headless, and offers the setup wizard when keyless in an interactive TTY. Because all four commands share it, onboarding behaviour is identical no matter which command a newcomer types first.

sequenceDiagram
    participant User
    participant CLI
    participant CredCheck as Credential Check
    participant Store as CredentialStore
    participant Detector as Local Detector
    participant Wizard as Setup Wizard
    participant LLM

    User->>CLI: praisonai run "hello"
    CLI->>CredCheck: is_configured()?
    CredCheck->>CredCheck: Check env vars
    CredCheck->>Store: Check ~/.praisonai/credentials.json
    Store-->>CredCheck: Not found
    CredCheck-->>CLI: False
    CLI->>Detector: detect_local_model()
    alt Local endpoint reachable
        Detector-->>CLI: LocalModel(ollama/llama3.2, base_url)
        CLI->>User: stderr: "No cloud key found; using local model ollama/llama3.2 …"
        CLI->>LLM: run against local base URL
        LLM-->>User: response
    else No local endpoint — is TTY?
        Detector-->>CLI: None
        alt TTY — interactive
            CLI->>User: "No API key configured. Run setup wizard? [Y/n]"
            User->>CLI: Y
            CLI->>Wizard: praisonai setup
            Wizard-->>CLI: Credentials stored
            Wizard->>LLM: Agent.start("Say hello in one sentence")
            LLM-->>Wizard: reply
            Wizard->>User: prints reply + ✅ Verified
            CLI->>User: Continues with run
        else non-TTY / --quiet / --output json
            CLI->>User: stderr: "No API key configured. Run: praisonai setup"
            CLI->>CLI: exit 1
        end
    end

Credential detection order

When no cloud key is present, PraisonAI adopts a reachable local endpoint before offering the wizard — the first praisonai run "..." works against a running Ollama on localhost:11434 with zero setup. See Keyless local-first fallback and Local Models.

Behaviour by Mode

This table applies to all four entrypoints (praisonai, run, code, chat) — they share the same ensure_configured_or_onboard() gate.

Headless triggers per entrypoint

“Headless” (interactive=False) is decided per command — this is what “non-TTY” means for each:

Standalone pip install praisonai-code (no wrapper)

Two entrypoints skip the gate when the wrapper isn’t installed so the resident TUI can surface its own actionable install hint (pip install praisonai[tui]) instead of a raw “No API key configured” exit:

• Bare praisonai and interactive praisonai chat (no prompt) run the gate only when the wrapper is available. On a bare praisonai-code install, the gate is skipped and the TUI shows its own hint.
• Single-prompt chat "…" and every praisonai code invocation always run the gate — no wrapper is needed to dispatch a single turn.

First command is praisonai code

A brand-new user whose first-ever command is praisonai code "add a test for foo" now lands in onboarding instead of a raw provider error.

$ praisonai code "add a test for foo"
No API key configured.
Would you like to run the setup wizard now? [Y/n]: Y
🚀 PraisonAI Setup Wizard
Choose your LLM provider: 1
Enter API key (hidden): ****
Verifying your setup...
✅ Verified — your agent is working!
[code assistant starts]

$ praisonai code -p "add a test for foo" --output json
Error: No API key configured. Run: praisonai setup
or set environment variables like OPENAI_API_KEY
(a running local endpoint such as Ollama would be used automatically)
$ echo $?
1

$ praisonai code "add a test for foo"
No cloud key found; using local model ollama/llama3.2. Run `praisonai setup` to add a hosted provider.
[code assistant starts against local Ollama]

The equivalent trio for praisonai chat uses --json for the headless line. See Chat → First-run credential gate and Code → First-run credential gate.

Keyless local-first (Ollama & OpenAI-compatible)

With a model already running locally, PraisonAI works before you configure any cloud key.

# Have Ollama running: `ollama serve` and `ollama pull llama3.2`
# Then just:
from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    instructions="You are a helpful assistant.",
)
agent.start("Say hi")
# The CLI/wrapper detects the local endpoint. No API key set,
# no `model=` argument, no OPENAI_BASE_URL export needed.

The same convenience applies straight from the terminal:

ollama serve
ollama pull llama3.2
praisonai "Summarise this repo"
# stderr: No cloud key found; using local model ollama/llama3.2. Run `praisonai setup` to add a hosted provider.

Endpoint precedence

The detector resolves the endpoint to probe in this order, then hits Ollama’s native /api/tags first (falling back to the OpenAI-compatible /v1/models):

Model id labels

The detected model id carries a provider prefix so it routes to the right path:

See also Keyless Local-First Run for the full deep-dive.

CI / Scripting

In non-interactive environments with no credentials and no reachable local endpoint, PraisonAI exits with code 1 and writes to stderr:

No API key configured. Run: praisonai setup
(a running local endpoint such as Ollama would be used automatically)

The second line is a reminder that a reachable local endpoint (Ollama or any OpenAI-compatible server) is adopted automatically — see Keyless Local-First Run.

Non-interactive detection: not sys.stdin.isatty() or --output json mode.

GitHub Actions example

- name: Run PraisonAI agent
  run: praisonai run "Summarize the changelog"
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Setting any of the detected cloud provider env vars silences the check completely — no code changes needed.

Keyless CI with an in-cluster Ollama sidecar

A CI runner that ships an Ollama sidecar can run keylessly by pointing OLLAMA_HOST at it — no cloud secret required:

- name: Run PraisonAI agent (local model)
  run: praisonai run "Summarize the changelog"
  env:
    OLLAMA_HOST: http://ollama:11434

Skipping the Prompt

Several ways to avoid the setup prompt:

Default model on first run

If you run a command like praisonai chat without --model on first use, PraisonAI picks a default that matches the provider credential it finds in your environment — Anthropic key → Claude, Gemini key → Gemini Flash, etc. The picker now selects a provider-appropriate model for Mistral, DeepSeek, xAI, Together, Perplexity, and Fireworks too (see the full 14-row table). When no cloud key is present, resolve_default_model() prefers a reachable local model (e.g. ollama/llama3.2) before falling back to the terminal default (gpt-4o-mini). A cloud-key provider always wins over the local model. See Default Model Resolution for the full ladder.

Run praisonai config provenance run.model any time to see which rung the resolver picked and why — see config provenance.

Best Practices

env:
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Related