> ## Documentation Index > Fetch the complete documentation index at: https://praison.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Default Model Selection > The CLI auto-selects the best available model from your credentials — no more hardcoded gpt-4o-mini When you don't specify a model, the CLI ranks every model your credential unlocks by capability and picks the best one. A one-line notice tells you what was chosen and why. The same resolver drives the SDK `Agent(llm=None)` path — construct an `Agent` with no `llm=` and it picks from your credentials too. > [!NOTE] > > [PR #5412](https://github.com/MervinPraison/PraisonAI/pull/5412) made the credential default **capability-ranked best-available** per provider; [PR #5750](https://github.com/MervinPraison/PraisonAI/pull/5750) hardened the ranking to **exclude Responses-API-only models** (like `gpt-5-pro`) and **rank dated snapshots below stable ids** (e.g. `gpt-5` beats `gpt-5-2025-08-07`). A run with only `OPENAI_API_KEY` now lands on the best **stable, Chat-Completions-callable** model your catalogue advertises. The `provider/` prefix is preserved so routing is unchanged. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import os from praisonaiagents import Agent os.environ["OPENAI_API_KEY"] = "sk-..." # No llm= and only OPENAI_API_KEY set — picks the best stable, chat-callable # OpenAI model in the catalogue (not gpt-5-pro, not gpt-5-2025-08-07). agent = Agent(instructions="Summarise the latest release notes.") agent.start("Give me the top three changes in the last PR.") ``` ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph LR subgraph "Default Model Selection" Request[📋 User Request] --> Process[⚙️ Default Model Selection] Process --> Result[✅ Result] end classDef input fill:#6366F1,stroke:#7C90A0,color:#fff classDef process fill:#189AB4,stroke:#7C90A0,color:#fff classDef output fill:#10B981,stroke:#7C90A0,color:#fff class Request input class Process process class Result output ``` ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} sequenceDiagram participant User participant Agent participant Feature as Default Model Selection User->>Agent: Request Agent->>Feature: Process request Feature-->>Agent: Result Agent-->>User: Response ``` ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} from praisonaiagents import Agent agent = Agent( name="Assistant", instructions="Help with tasks", ) agent.start("Summarise the key points from this week") ``` The user omits `--model`; the CLI picks the best credential-backed model and prints what it chose. ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph LR subgraph "Default Model Selection" In[📝 Command no --model] --> Scan[🔍 Scan Credentials] Scan --> Pick[⚙️ Pick Best Model] Pick --> Agent[🤖 Agent] Agent --> Out[✅ Response + Notice] end classDef input fill:#6366F1,stroke:#7C90A0,color:#fff classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff classDef output fill:#10B981,stroke:#7C90A0,color:#fff class In input class Scan,Pick process class Agent agent class Out output ``` ## How It Works ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} sequenceDiagram participant User participant CLI participant Resolver participant Agent User->>CLI: praisonai "task" (no --model) CLI->>Resolver: Resolve default model Resolver-->>CLI: Best credential-backed model CLI->>Agent: Build with chosen model Agent-->>User: Response + "using " notice ``` ### Resolution Order ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph TB subgraph "Default Model Resolution Order" E["1️⃣ Explicit --model flag\nor config / YAML"] -->|"wins immediately"| USE["✅ Use this model"] E -->|Not set| R["2️⃣ Most-recently-used\n~/.praisonai/state/model.json"] R -->|Found| USE R -->|Not found| ENV["3️⃣ MODEL_NAME or\nOPENAI_MODEL_NAME env var"] ENV -->|Set| USE ENV -->|Not set| CRED{"4️⃣ Credential scan"} CRED -->|First present credential| RANK["🏅 Rank that provider's\nmodels by capability"] CRED -->|Nothing found| FB["gpt-4o-mini (fallback)"] RANK -->|Best id, prefix preserved| USE RANK -->|Ranking yields nothing| REP["Degrade to fixed\nrepresentative\n(gpt-4o-mini for OpenAI)"] REP --> USE FB --> USE end classDef explicit fill:#8B0000,stroke:#7C90A0,color:#fff classDef mru fill:#189AB4,stroke:#7C90A0,color:#fff classDef env fill:#6366F1,stroke:#7C90A0,color:#fff classDef cred fill:#F59E0B,stroke:#7C90A0,color:#fff classDef use fill:#10B981,stroke:#7C90A0,color:#fff class E explicit class R mru class ENV env class CRED,RANK,REP,FB cred class USE use ``` ### How the ranking works When only a credential is set, the CLI ranks every model that credential unlocks by capability (tool-use, context, reasoning, vision) and uses the best-available one — not a fixed cheap default. * Prefers tool-use (essential for agentic work). * **Excludes models whose LiteLLM `mode` is not `chat`** (e.g. OpenAI Responses-API-only ids like `gpt-5-pro` are filtered out — the Chat Completions path can't call them). Entries with no `mode` are kept, so older cached catalogues still work. * De-prioritises unstable preview / experimental / `-auto` ids. * **De-prioritises dated snapshot ids** matching `-YYYY-MM-DD` or `-YYYYMMDD` (e.g. `gpt-5-2025-08-07`, `claude-3-5-haiku-20241022`) so the stable alias wins. * De-prioritises `-mini` / `nano` / `small` / `lite` / `haiku` / `flash` / `3.5-turbo` class ids. * Then larger `max_context`, then reasoning, then vision. * Non-chat ids by **name** (embeddings, rerankers, speech, image, moderation, vision-encoder, clip) are also excluded from the chat default. * Google/Gemini aliasing: a `GEMINI_API_KEY`-only run still ranks litellm's `google`-labelled Gemini models (and vice-versa). The ranking returns a bare id, but the **provider prefix is preserved** — `anthropic/`, `gemini/`, `cohere/`, `openrouter/openai/`, etc. keep their prefix so runtime routing is unchanged. If ranking yields nothing — including when every candidate was filtered out by the mode or name gates — `best_available()` returns `None` and selection degrades to the historical fixed representative (`gpt-4o-mini` for OpenAI). ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph LR subgraph "Capability Ranking" MODE["🚫 Non-chat mode\nexcluded"] --> NAME["🚫 Non-chat names\nexcluded"] NAME --> T[🔧 Tool-use] T --> S["🧱 Stable + non-dated\nnon-preview"] S --> M[📈 Non-mini class] M --> C[📐 Larger context] C --> R[🧠 Reasoning] R --> V[👁️ Vision] V --> B[✅ Best id] end classDef gate fill:#8B0000,stroke:#7C90A0,color:#fff classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff classDef filter fill:#F59E0B,stroke:#7C90A0,color:#fff classDef best fill:#10B981,stroke:#7C90A0,color:#fff class MODE,NAME gate class T tool class S,M,C,R,V filter class B best ``` > [!TIP] > > Keep the catalogue current so a newly released flagship is ranked — run [`praisonai models refresh`](https://praison.ai/docs/features/models-cli#praisonai-models-refresh). ## Quick Start **1. Auto-pick model from credentials** Set your API key and run any command — no `--model` needed: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} export ANTHROPIC_API_KEY=sk-ant-... praisonai chat "Tell me a joke" ``` ``` No model set; using claude-sonnet-4-5 because ANTHROPIC_API_KEY is present. ``` The one-line notice only appears when a provider-inferred default is used (not when using the MRU or an explicit override). **2. Override for a single run** ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai chat --model gpt-4o "Explain quantum entanglement" ``` This model is saved as the most-recently-used and will be the default for the next run. **3. Pin the model for the project** Add a `.praison.json` to your project root: ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "model": "anthropic/claude-3-5-sonnet-20241022" } ``` Every `praisonai` command in this directory now uses this model. **4. Check with praisonai doctor** ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai doctor ``` Shows which credentials are present and which model would be selected on the next zero-config run. *** ## Resolution Order | Priority | Source | Persisted as MRU? | | - | - | :-: | | 1 (highest) | `--model` flag / config / YAML | ✅ Yes | | 2 | Most-recently-used (`~/.praisonai/state/model.json`) | — | | 3 | `MODEL_NAME` or `OPENAI_MODEL_NAME` env var | ✅ Yes | | 4 | Provider credential probe — capability-ranked best-available for the first present credential (prefix preserved) | ❌ No | | 5 (lowest) | `gpt-4o-mini` hard fallback | ❌ No | Provider-inferred defaults (priority 4) and the `gpt-4o-mini` fallback (priority 5) are **intentionally not persisted** as MRU. Persisting them would let a stale default win over fresh credential-based inference on a later run when your available providers have changed. *** ## MRU State The most-recently-used model is stored at: ``` ~/.praisonai/state/model.json ``` This honours `PRAISONAI_HOME` (`$PRAISONAI_HOME/state/model.json` when set). The legacy `~/.praison/state/model.json` is still read as a fallback. Content: ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} {"model": "claude-sonnet-4-5"} ``` To reset it (force credential-based re-inference): ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} rm ~/.praisonai/state/model.json ``` Or simply run with an explicit `--model` — that overwrites the MRU automatically. *** ## Best Practices > [accordion] Pin the model in CI > > Don't rely on auto-selection in automated pipelines. CI environments often have credentials for multiple providers, and the selected model can change if you add or remove a key. > > ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} > - name: Run agent task > env: > ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} > MODEL_NAME: "anthropic/claude-3-5-sonnet-20241022" > run: praisonai run task.yaml > ``` > [accordion] Watch the transparency notice in development > > The transparency notice (`No model set; using X because Y is present.`) only fires for provider-inferred defaults. If you see it unexpectedly in a staging environment, your `.praison.json` or `MODEL_NAME` env var may not be set. > [accordion] OPENAI\_MODEL\_NAME is still honoured > > For backward compatibility, the `OPENAI_MODEL_NAME` environment variable still overrides credential-based inference. If you have a legacy `.env` with this variable, it takes priority over the credential probe. > [accordion] Why your zero-config default isn't the newest flagship > > Two safety filters keep the default stable and callable: > > * **LiteLLM `mode` filter.** Ids the catalogue marks `mode: "responses"` (Responses API only) are excluded, e.g. `gpt-5-pro` / `gpt-5-pro-2025-10-06`. [PR #5750](https://github.com/MervinPraison/PraisonAI/pull/5750). > * **Dated snapshot filter.** `gpt-5-2025-08-07` and `claude-3-5-haiku-20241022` style ids rank below their stable aliases. > > To force a specific id anyway, use `Agent(llm="…")`, `--model`, or `MODEL_NAME` / `OPENAI_MODEL_NAME`. *** ## Related > [card] [CLI OAuth Login](https://praison.ai/docs/features/cli-oauth-login.md) > > Sign in to providers using browser-based OAuth > [card] [Models CLI](https://praison.ai/docs/features/models-cli.md) > > List, compare, and switch between available models This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.