Skip to main content
PraisonAI leads you to a verified, working agent in as few keystrokes as possible — auto-detecting any provider key you already have, 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 offers the setup wizard instead of failing on the first model call.

​
Onboarding Flow

​
Quick Start

1

Run praisonai without any setup

praisonai
If no credentials are configured, 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: 1) OpenAI  2) Anthropic  3) Google  4) Ollama  5) Custom
# Enter your API key when prompted
When one of OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, or GOOGLE_API_KEY is already exported, the wizard skips the menu and pre-selects that provider — you only confirm.
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 provider menu only appears when no key is detected.
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.
Pass --no-verify to skip the smoke test when running offline or in CI:
praisonai setup --no-verify --non-interactive \
  --provider openai --api-key "$OPENAI_API_KEY"
The wizard still writes the config; it just doesn’t dial the LLM.

​
How It Works

Both praisonai (bare) and praisonai run perform a credential check before doing any work.

​
Credential detection order

StepWhat is checkedExample
1. Env vars (fast path)OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, COHERE_API_KEYexport OPENAI_API_KEY=sk-...
2. Credential store~/.praisonai/credentials.json written by praisonai setup (also mirrored to ~/.praisonai/.env)praisonai setup
3. LLM resolutionresolve_llm_endpoint_with_credentials() — final fallbackStored OpenAI base URL
4. Setup wizard auto-detectionSame *_API_KEY env vars, offered as pre-selected default when the user is inside the wizardDetected on wizard entry, not first Agent.start()

​
Behaviour by Mode

ScenarioOld behaviourNew behaviour
Configured user (env var or stored credential)Works normallyWorks — no extra prompts, no added latency
New TTY user, no credentials, praisonaiLaunched TUI, failed on first LLM callAuto-detects any provider key already in the environment (confirm to use), otherwise prompts the menu; validates the key; runs a smoke-test with Agent.start(...); prints the reply.
New TTY user, no credentials, praisonai run "hi"Ran agent, failed on first LLM callSame prompt as above; on success continues the run
CI / piped stdin / --output jsonCryptic LLM failureWrites error to stderr, exits 1

​
CI / Scripting

In non-interactive environments, PraisonAI exits with code 1 and writes to stderr: 
No API key configured. Run: praisonai auth login
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 6 detected env vars silences the check completely — no code changes needed.

​
Skipping the Prompt

Three ways to avoid the setup prompt:
MethodCommand / Action
Set an env varexport OPENAI_API_KEY=sk-...
Run setup ahead of timepraisonai setup
Answer “No” at the promptType n → exits 0 with a hint to run praisonai auth login

​
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. See Default Model Resolution for the full ladder.

​
Best Practices

Set OPENAI_API_KEY (or the provider key for your model) as a repository secret, then reference it in your workflow env block. This is the recommended approach — no credential files in your repo, no interactive prompts:
env:
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
On shared developer machines, stored credentials (praisonai setup) are scoped to the user’s home directory and avoid environment variable leakage between sessions. Run praisonai setup config --show to verify what is stored.
Run praisonai run "ping" manually before wiring the command into a pipeline or CI job. A successful response confirms credentials are configured and the model is reachable.
The smoke test is convenient locally but wastes a token round-trip in CI. Skip it with --no-verify on both setup and setup wizard.

Setup Wizard

Interactive wizard for configuring LLM provider credentials

Run Command

Run agents from files or prompts