Skip to main content
Interactive wizard that stores your LLM provider API key so every subsequent praisonai command works without extra configuration.
Running praisonai --init without a configured provider prints a pointer to this page — you do not have to find setup separately.

​
Quick Start

1

Run the setup wizard

praisonai setup
The interactive wizard walks you through provider selection and key entry.
2

Confirm the detected provider

If a provider key is already in your environment, the wizard confirms it instead of showing the menu (the wizard inspects the environment — it isn’t tied to any one provider):
Detected ANTHROPIC_API_KEY in your environment.
Use Anthropic (claude-sonnet-4-20250514)? [Y/n]:
Press Enter to accept, or answer n to pick a different provider from the numeric menu.
3

Choose a provider (fallback)

Shown only when no *_API_KEY was detected or you declined the detected one.
🚀 PraisonAI Setup Wizard

1. Choose your LLM provider:
  1) OpenAI (GPT-4o, GPT-4, GPT-3.5)
  2) Anthropic (Claude)
  3) Google (Gemini)
  4) Ollama (Local models)
  5) Custom provider

Select provider [1]:
4

Enter your API key

2. Enter your OpenAI API key:
Enter API key (hidden):
The key is validated against the provider’s expected format (same check as auth login); a bad key re-prompts up to three times before setup proceeds. Keys are stored in ~/.praisonai/.env with permissions 0600.
5

Verified automatically

Verifying your setup...
✅ Verified — your agent is working!
Hello!
Setup runs a one-shot Agent.start("Say hello in one sentence") and prints the reply. Skip with --no-verify in offline/CI.

​
CLI Flags

praisonai setup [OPTIONS] [COMMAND]
OptionDescription
--non-interactiveRun without prompts (requires --provider and --api-key)
--provider TEXTProvider: openai, anthropic, google, ollama, custom
--api-key TEXTAPI key for the provider
--model TEXTDefault model to use
--no-verifySkip the post-setup smoke test (offline/CI). Available on setup and setup wizard.
The --no-verify flag applies to both setup and setup wizard — the sub-command inherits it.

​
Subcommands

CommandDescription
setup wizardExplicitly run the interactive wizard
setup config --showShow current configuration (API keys masked)
setup config --editOpen configuration in $EDITOR
setup resetRemove stored credentials
setup reset --forceRemove without confirmation

​
Non-interactive Mode

For CI/CD or scripted setup: 
praisonai setup --non-interactive \
  --provider openai \
  --api-key "$OPENAI_API_KEY" \
  --model gpt-4o-mini \
  --no-verify  # skip the smoke test in CI so we don't hit the network
Supported providers and their auto-detected env vars — set any one of these and the wizard pre-selects that provider:
Provider--provider valueEnv var detected / written
OpenAIopenaiOPENAI_API_KEY
AnthropicanthropicANTHROPIC_API_KEY
GooglegoogleGEMINI_API_KEY or GOOGLE_API_KEY
Ollamaollama(no key needed)
Customcustom(user-defined)

​
Post-setup smoke test

After the wizard writes your config, it runs one live call to confirm the credential is good.
StepBehaviour
Constructs AgentAgent(name="setup-check", llm=<model>)
Runs a promptagent.start("Say hello in one sentence")
On successPrints the reply and Verified — your agent is working!
On failurePrints a warning and points at praisonai doctor; never aborts setup
No modelSkipped silently (see non-interactive mode without --model)
Passing case — the reply is printed and the agent is confirmed working: 
Verifying your setup...
✅ Verified — your agent is working!
Hello! How can I help you today?
Failing case — a bad key or no network. The config is still saved; the failure is a warning, not an abort: 
Verifying your setup...
⚠️  Verification failed: AuthenticationError - invalid api key
Your config was saved. Check your key/model, then run praisonai doctor.
Skip the smoke test entirely for offline or CI installs: 
praisonai setup --no-verify --non-interactive \
  --provider openai --api-key sk-...
Use --no-verify in CI or offline installs where the smoke test would fail due to no network.
If verification fails, your config is already saved — run praisonai doctor to diagnose the key or model.

​
Where Credentials Are Stored

praisonai setup now writes three files so the same key is visible to every CLI code path (setup, auth list, run / inject_credentials_into_env):
FilePurposePermissions
~/.praisonai/.envAPI keys as KEY=value lines (primary artifact — this is what agents read via env vars)0600
~/.praisonai/config.yamlProvider name, default model, telemetry flag0600
~/.praisonai/credentials.jsonMirror of the API key into the unified credential store — the same file praisonai auth list reads and that inject_credentials_into_env() uses at run time0600
The credential-store mirror means a key set via praisonai setup shows up in praisonai auth list and is picked up by praisonai run without exporting anything.
Legacy path migration. Prior releases used ~/.praison/credentials.json. That location is now a read-only backward-compat fallback: it’s still read if the canonical ~/.praisonai/credentials.json doesn’t exist yet, and any write transparently migrates your old entries onto the canonical file. You don’t need to re-run auth login or lose any stored providers — running setup (or any auth login) once completes the migration. No re-login is required.
Local providers like ollama (no API key) are skipped for the credential-store mirror — only providers with a real key/env var are written to credentials.json. If the mirror step fails for any reason (permissions, disk full), setup prints a warning and continues — the .env file is the primary artifact and is written first.
PRAISONAI_HOME is honoured. When PRAISONAI_HOME points at a non-default directory, setup writes credentials.json under that directory. When it equals the default ~/.praisonai, setup keeps the legacy-fallback + migration path active.
All sensitive files are written with chmod 600 and are never included in any telemetry data.

​
What happens if you skip --model

When you don’t pass --model to setup (or when you run a command like praisonai chat with no --model), PraisonAI picks a sensible default that matches the provider you actually have a key for — it no longer always picks an OpenAI model. 
from praisonaiagents import Agent

# Only ANTHROPIC_API_KEY is set in the environment — Agent picks
# anthropic/claude-3-5-sonnet-latest automatically.
agent = Agent(name="Research Agent", instructions="Summarise news")
agent.start("What happened in AI today?")

​
Resolution precedence

StepSourceNotes
1Explicit --model / llm= arg / YAML / configWins, persisted as the recent model
2Most-recently-used model (~/.praison/state/model.json)Only user-chosen values are remembered
3MODEL_NAME env var (then OPENAI_MODEL_NAME for backward compatibility)Persisted on use
4First present provider credential (table below)Not persisted — kept fresh per run
5Terminal fallback (DEFAULT_FALLBACK_MODEL — currently gpt-4o-mini)Not persisted

​
Credential → default-model map

The first credential found wins, in this order: This map is run-time inference (_PROVIDER_DEFAULTS in llm/env.py) — used when an Agent starts with no explicit model:
Credential env varDefault model picked
OPENAI_API_KEYDEFAULT_FALLBACK_MODEL (gpt-4o-mini)
ANTHROPIC_API_KEYanthropic/claude-3-5-sonnet-latest
GEMINI_API_KEYgemini/gemini-1.5-flash
GOOGLE_API_KEYgoogle/gemini-1.5-flash
GROQ_API_KEYgroq/llama-3.3-70b-versatile
COHERE_API_KEYcohere/command-r
OPENROUTER_API_KEYopenrouter/openai/gpt-4o-mini
OLLAMA_HOSTollama/llama3.2
The setup wizard shows its own refreshed defaults from SetupHandler._provider_defaults() — Anthropic claude-sonnet-4-20250514, Google gemini-2.5-flash, and OpenAI sourced from DEFAULT_FALLBACK_MODEL. These are the values pre-filled at the model-selection step; the run-time inference table above is the fallback used later when an Agent starts without an explicit model.
The first time a provider-aware default is inferred, the CLI prints a one-line notice: 
No model set; using anthropic/claude-3-5-sonnet-latest because ANTHROPIC_API_KEY is present.
Only user-chosen values (explicit --model, env overrides) are persisted as the recent model. Provider-inferred defaults and the terminal fallback (DEFAULT_FALLBACK_MODEL, currently gpt-4o-mini) are deliberately not persisted — this keeps model selection fresh if your available providers change between runs.
The recency file lives at ~/.praison/state/model.json (note: .praison, not .praisonai). It is created on demand; if it’s missing or unreadable, resolution falls straight through to provider inference and works normally.

​
When Does Setup Run Automatically?

If you skip setup at install time (or run --no-prompt), the first praisonai or praisonai run command detects the missing credentials and offers to launch this wizard for you. See First-run Onboarding for the full flow.

​
Best Practices

praisonai setup is idempotent — running it again overwrites the previous configuration. Use it whenever you switch providers or need to rotate an API key.
In CI environments set OPENAI_API_KEY (or the provider-specific key) as a secret. On developer workstations use praisonai setup so you don’t have to set env vars in every shell session.
praisonai setup config --show
# Output: OPENAI_API_KEY=***
API keys are masked in the output. Only non-sensitive settings (provider, model) appear in plaintext.
With just one credential env var set (e.g. ANTHROPIC_API_KEY), running praisonai chat without --model now picks the matching default automatically. You only need --model to override or to mix providers in one session.
By default praisonai setup finishes by running a one-shot Agent.start(...) to confirm your key and model work. If you’re setting up offline or in CI where the smoke test would fail, pass --no-verify.

First-run Onboarding

Auto-detects missing credentials at first invocation

Quick Start (--init)

Generate agents.yaml with praisonai --init — links here when no provider is configured

Run Command

Run agents from files or prompts

CLI Reference

Complete command tree and flag reference

Installer Internals

How the installer sets up credentials at install time