Praison AI

Setup

Interactive wizard for configuring LLM provider credentials

Interactive wizard that stores your LLM provider API key so every subsequent praisonai command works without extra configuration.

Diagram

or skip setup entirely

Yes

🚀 praisonai setup

🔎 Auto-detect key

Choose provider

Enter + validate key

Choose default model

Telemetry consent

💾 Save to ~/.praisonai/

🧪 Smoke test

✅ Ready to use

🖥️ Local endpoint reachable?

Quick Start

  1. Run the setup wizard
    bash
    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. The menu is now catalogue-driven, built from ModelCatalogue.list_providers() — openai, anthropic, google, ollama first, every other catalogue provider (Groq, OpenRouter, Mistral, DeepSeek, xAI, …) next, and custom last — not a hardcoded five:

    🚀 PraisonAI Setup Wizard

Choose your LLM provider:
  1) OpenAI
  2) Anthropic
  3) Google
  4) Ollama
  5) Groq
  6) OpenRouter
  7) Mistral
  8) DeepSeek
  ...
  N) Custom

Select provider [1]:
  4. Enter your API key

    A Get your key: link to the provider’s key-creation page prints before the hidden prompt for catalogue providers:

    Get your key: https://console.groq.com/keys
2. Enter your Groq 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.

    6. CLI Flags

    bash
    praisonai setup [OPTIONS] [COMMAND]
    OptionDescription
    --non-interactiveRun without prompts (requires --provider and --api-key)
    --provider TEXTAny catalogue-known provider (openai, anthropic, google, groq, openrouter, mistral, deepseek, ollama, custom, …). Non-curated providers derive `

    _API_KEY automatically | | –api-key TEXT | API key for the provider | | –model TEXT | Default model to use | | –no-verify | Skip 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:

    bash
    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

    Curated 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)

    Any catalogued provider (Mistral, DeepSeek, xAI, Together, Perplexity, Fireworks, …) is now auto-detected by --non-interactive in addition to the curated four — set MISTRAL_API_KEY (or any catalogued key) and praisonai setup --non-interactive picks it up without --provider. You don’t need to know about the catalogue to benefit. See the full Credential → default-model map for the 14 detected keys.

    Any catalogue provider

    --provider in non-interactive mode accepts any provider returned by ModelCatalogue.list_providers() — not just the five above. For a catalogue provider without a curated row, the env-var name is derived as `

    _API_KEY`:

    bash
    # Writes DEEPSEEK_API_KEY to ~/.praisonai/.env
praisonai setup --non-interactive --provider deepseek --api-key sk-...

    groq → GROQ_API_KEY, openrouter → OPENROUTER_API_KEY, and so on. A few providers keep a canonical override: google/gemini → GEMINI_API_KEY, perplexity → PERPLEXITYAI_API_KEY.

    Providers with multiple env-var spellings round-trip back under the same alias you set:

    ProviderAlias env vars (honoured in order set)Fallback when neither set
    togetherTOGETHER_API_KEY / TOGETHERAI_API_KEYTOGETHER_API_KEY
    fireworksFIREWORKS_API_KEY / FIREWORKS_AI_API_KEYFIREWORKS_API_KEY
    google / geminiGEMINI_API_KEY / GOOGLE_API_KEYGEMINI_API_KEY

    Setting TOGETHERAI_API_KEY (or FIREWORKS_AI_API_KEY) writes back to that same spelling — the run no longer ends without a resolved key. Existing google / gemini alias behaviour is unchanged.

    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:

    bash
    praisonai setup --no-verify --non-interactive \
  --provider openai --api-key sk-...

    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.

    setup writes to the same canonical home that every other CLI subsystem — sessions, traces, logs, cache, config set — reads. PRAISONAI_HOME re-roots all of them together (see CLI Home Root).

    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.

    python
    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?")
    Diagram

    Yes

    No

    Yes

    No

    Yes

    No

    Yes

    No

    🚀 No –model given

    Explicit
    config?

    ✅ Use explicit
    Persist as recent

    Recent model
    on disk?

    ✅ Reuse recent

    MODEL_NAME or
    OPENAI_MODEL_NAME?

    ✅ Use env
    Persist as recent

    Provider credential
    present?

    ✅ Provider default
    Not persisted

    gpt-4o-mini

    Resolution precedence

    StepSourceNotes
    1Explicit --model / llm= arg / YAML / configWins, persisted as the recent model
    2Most-recently-used model (~/.praisonai/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)Capability-ranked best-available for that provider; not persisted — kept fresh per run
    5Terminal fallback (DEFAULT_FALLBACK_MODEL — currently gpt-4o-mini)Used only when no credential is present; not persisted

    Credential → default-model map

    The first credential found wins, in this order:

    This map is now derived from PROVIDER_ENV_CATALOGUE in praisonai_code/llm/catalogue.py — one source of truth for first-run auto-detection and default-model inference. _PROVIDER_DEFAULTS in llm/env.py derives from the same catalogue (with a literal fallback), so run-time inference and setup detection stay in sync. Adding a provider is now a data row, not spread-out code.

    Credential env varDefault model picked
    OPENAI_API_KEYbest OpenAI chat model (e.g. gpt-4o) — capability-ranked best-available, not DEFAULT_FALLBACK_MODEL
    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
    MISTRAL_API_KEYmistral/mistral-large-latest
    DEEPSEEK_API_KEYdeepseek/deepseek-chat
    XAI_API_KEYxai/grok-2-latest
    TOGETHER_API_KEY or TOGETHERAI_API_KEYtogether_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo
    PERPLEXITYAI_API_KEYperplexity/sonar
    FIREWORKS_API_KEY or FIREWORKS_AI_API_KEYfireworks_ai/accounts/fireworks/models/llama-v3p3-70b-instruct
    Local endpoint reachable at OPENAI_BASE_URL / OLLAMA_HOST / 127.0.0.1:11434 (no cloud key)ollama/<detected name> (or openai/<id> for non-Ollama local servers)

    The historical eight stay at the head of the catalogue, so ordered-preference behaviour is unchanged — OPENAI_API_KEY still wins when both it and MISTRAL_API_KEY are present. The additions are purely additive and backward compatible. When a provider declares multiple env-var spellings (Together, Fireworks), whichever you actually set is honoured for both detection and the credential written back.

    The last row is the detection case — when no cloud key is set, PraisonAI probes for a running local endpoint and adopts what detect_local_model() returns. See Keyless Local-First Run.

    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.

    When Does Setup Run Automatically?

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

    Best Practices

    Re-run setup to change provider or rotate keys

    praisonai setup is idempotent — running it again overwrites the previous configuration. Use it whenever you switch providers or need to rotate an API key.

    Use env vars in CI, stored credentials on workstations

    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.

    Inspect what is stored without exposing keys
    bash
    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 one credential set, –model is optional

    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. On first run, the same resolved model is validated by the onboarding gate.

    Verify your setup automatically

    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.

    Related

    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