> ## 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.

# CLI Configuration

> One config, every project: layered, project-aware defaults for the praisonai CLI

The `praisonai` CLI reads defaults from a layered hierarchy so you can set a model once and have it work everywhere — globally, per project, or per command.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Use project defaults from .praisonai/config.yaml.")
agent.start("What model am I using?")
```

The user sets a default model in config once; every `praisonai` command in that project picks it up without repeating flags.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Configuration Precedence (highest wins)"
        CLI[⚡ CLI flags] --> ENV[🌱 Environment variables]
        ENV --> PROJ[📁 Project config<br/>.praisonai/config.yaml]
        PROJ --> GLOB[🏠 Global config<br/>~/.praisonai/config.yaml]
        GLOB --> DEF[📋 Built-in defaults]
    end

    classDef high fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef mid fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef low fill:#6366F1,stroke:#7C90A0,color:#fff

    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff
    class CLI,ENV high
    class PROJ,GLOB mid
    class DEF low
```

## Quick Start

<Steps>
  <Step title="Set a default model">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai config set agent.model gpt-4o-mini
    ```
  </Step>

  <Step title="Run any agent">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai run "Summarise this README"
    ```

    The model from config is picked automatically — no `--model` flag needed.
  </Step>

  <Step title="Inspect what was resolved">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai config show --sources
    ```
  </Step>
</Steps>

When you `praisonai run`, CLI defaults flow into the agent automatically:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

# Model, temperature, and tools come from resolved CLI config
agent = Agent(name="assistant", instructions="Be helpful.")
# praisonai run "..." uses agent.model from ~/.praisonai/config.yaml or project config
```

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CLI as praisonai CLI
    participant Resolver as ConfigResolver
    participant Project as Project config
    participant Agent

    User->>CLI: praisonai run "task"
    CLI->>Resolver: resolve_config()
    Resolver->>Project: walk-up discovery from cwd
    Project-->>Resolver: .praisonai/config.yaml
    Resolver-->>CLI: merged ResolvedConfig
    CLI->>Agent: agent.model, temperature, tools
    Agent-->>User: response
```

Layers are **deep-merged**. Lists are concatenated. Scalars are overridden by higher layers.

| Layer | Source                                             | Precedence |
| ----- | -------------------------------------------------- | ---------- |
| 1     | Built-in defaults                                  | Lowest     |
| 2     | Global `~/.praisonai/config.yaml` (+ legacy paths) |            |
| 3     | Project config (walk-up to git root)               |            |
| 4     | Environment variables                              |            |
| 5     | CLI flags                                          | Highest    |

***

## Project vs Global Config

| Location                           | Scope                             | Commit to repo? |
| ---------------------------------- | --------------------------------- | --------------- |
| `~/.praisonai/config.yaml`         | All projects on this machine      | No              |
| `./.praisonai/config.yaml`         | This project (and subdirectories) | Yes             |
| `./praison.yaml` / `./praison.yml` | Alternative project names         | Yes             |
| `./.praison/config.toml`           | Legacy TOML (backward compat)     | Optional        |

Walk-up discovery searches, at each directory from `cwd` up to the git root:

1. `.praisonai/config.yaml`
2. `.praisonai/config.yml`
3. `praison.yaml`
4. `praison.yml`
5. `.praison/config.toml` (legacy)

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# .praisonai/config.yaml — commit this to your repo
agent:
  model: claude-sonnet-4-6
  temperature: 0.3
  max_tokens: 16000
  tools:
    - search_web
    - read_file
```

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Anywhere inside the repo (including subdirs):
praisonai run "Find recent benchmarks for retrieval-augmented generation"
# Uses claude-sonnet-4-6 automatically — no --model flag needed
```

***

## Choose Your Scope

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q{Where should this setting live?}
    Q -->|Just this one command| A[CLI flag]
    Q -->|This shell session only| B[Environment variable]
    Q -->|This repo / team-wide| C[Project config<br/>.praisonai/config.yaml]
    Q -->|All my projects| D[Global config<br/>~/.praisonai/config.yaml]

    classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef option fill:#10B981,stroke:#7C90A0,color:#fff
    class Q question
    class A,B,C,D option
```

***

## Configuration Schema

### `agent.*` defaults

| Key                   | Type             | Default | Notes                                   |
| --------------------- | ---------------- | ------- | --------------------------------------- |
| `agent.model`         | `str`            | `None`  | e.g. `gpt-4o-mini`, `claude-sonnet-4-6` |
| `agent.provider`      | `str`            | `None`  | e.g. `openai`, `anthropic`              |
| `agent.base_url`      | `str`            | `None`  | Custom LLM base URL                     |
| `agent.tools`         | `list[str]`      | `[]`    | Default tool names                      |
| `agent.toolset`       | `str`            | `None`  | Named toolset                           |
| `agent.default_agent` | `str`            | `None`  | Default agent slug                      |
| `agent.memory`        | `bool` or `dict` | `None`  | Enable memory or config dict            |
| `agent.stream`        | `bool`           | `True`  | Stream responses                        |
| `agent.temperature`   | `float`          | `0.7`   | LLM temperature                         |
| `agent.max_tokens`    | `int`            | `16000` | LLM token budget                        |

<Note>
  `api_key` is never serialised to YAML — use environment variables or [`praisonai auth`](/docs/cli/auth).
</Note>

### `mcp.servers.<name>`

| Key       | Type                 | Default | Description                                                                                    |
| --------- | -------------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `command` | `list[str]` or `str` | —       | Local (stdio) server launch command. List form preferred.                                      |
| `args`    | `list[str]`          | `[]`    | Extra args appended to `command`.                                                              |
| `env`     | `dict[str, str]`     | `{}`    | Env vars for the server process. Values containing `,` are skipped on the command-string path. |
| `enabled` | `bool`               | `true`  | Set `false` to declare-but-not-wire a server.                                                  |
| `type`    | `"remote"`           | —       | Marks a remote server; skipped by the run command-string path.                                 |
| `url`     | `str`                | —       | Remote endpoint; presence implies remote.                                                      |

### `permissions.*`

| Key         | Type                             | Default | Description                                                       |
| ----------- | -------------------------------- | ------- | ----------------------------------------------------------------- |
| `default`   | `"allow"` \| `"deny"` \| `"ask"` | —       | Fallback action when no rule matches.                             |
| `rules`     | `list[{pattern, action}]`        | `[]`    | Structured rule list. `action` must be `allow`, `deny`, or `ask`. |
| `<pattern>` | `"allow"` \| `"deny"` \| `"ask"` | —       | Flat shorthand — same shape as `--allow`/`--deny` produces.       |

Example combining all three sections:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# .praisonai/config.yaml
agent:
  model: gpt-4o
  temperature: 0.3

mcp:
  servers:
    playwright:
      command: ["npx", "-y", "@playwright/mcp"]

permissions:
  default: ask
  rules:
    - { pattern: "bash:git *", action: allow }
    - { pattern: "bash:rm *",  action: deny }
```

See [Single-Source Config](/docs/features/single-source-config) for a full guide to using all three sections together. Other top-level sections (`output`, `traces`, `session`) are also valid — see [Config CLI reference](/docs/cli/config).

***

## Validation

Configuration is validated against a published JSON Schema. Unknown keys produce actionable warnings with typo suggestions; opt into strict mode to fail fast.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    L[📄 .praisonai/config.yaml] --> R[🔍 Schema check]
    R -->|Known keys| OK[✅ Applied]
    R -->|Unknown key| W[⚠ Warn + suggest]
    R -->|Strict mode| E[❌ Raise ValueError]

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
    classDef warn fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef err fill:#8B0000,stroke:#7C90A0,color:#fff

    class L input
    class R process
    class OK ok
    class W warn
    class E err
```

| Mode              | Enable via                                        | Behaviour on unknown key                   |
| ----------------- | ------------------------------------------------- | ------------------------------------------ |
| Warn (default)    | —                                                 | Logs `UserWarning`, valid keys still apply |
| Strict (per-call) | `--strict-config` / `ConfigResolver(strict=True)` | Raises `ValueError`                        |
| Strict (global)   | `PRAISONAI_STRICT_CONFIG=1`                       | All resolver calls strict                  |

Typo example:

```
Unknown config key 'temprature' in .praisonai/config.yaml (section: agent). Did you mean 'temperature'?
```

The `# yaml-language-server: $schema=...` line written by `praisonai init` enables real-time autocomplete and inline errors in VS Code (YAML extension) and other LSP-aware editors against the [published schema](https://raw.githubusercontent.com/MervinPraison/PraisonAI/main/src/praisonai/praisonai/cli/configuration/config.schema.json).

***

## Environment Variables

| Variable                  | Maps to          | Notes                  |
| ------------------------- | ---------------- | ---------------------- |
| `MODEL_NAME`              | `agent.model`    |                        |
| `OPENAI_MODEL_NAME`       | `agent.model`    |                        |
| `PRAISONAI_MODEL`         | `agent.model`    |                        |
| `PRAISONAI_PROVIDER`      | `agent.provider` |                        |
| `OPENAI_BASE_URL`         | `agent.base_url` |                        |
| `OPENAI_API_BASE`         | `agent.base_url` |                        |
| `PRAISONAI_BASE_URL`      | `agent.base_url` |                        |
| `PRAISONAI_OUTPUT_FORMAT` | `output.format`  |                        |
| `PRAISONAI_COLOR`         | `output.color`   | bool: `true`/`1`/`yes` |
| `PRAISONAI_VERBOSE`       | `output.verbose` | bool                   |
| `PRAISONAI_QUIET`         | `output.quiet`   | bool                   |
| `PRAISONAI_TELEMETRY`     | `telemetry`      | bool                   |

***

## Subcommand Reference

| Command                            | Flags                                        | Behaviour                                                                 |
| ---------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
| `praisonai config show`            | `--format yaml\|json\|table`, `--sources/-s` | Prints fully resolved config; with `--sources`, lists contributing layers |
| `praisonai config validate [FILE]` | `--strict-config`, `--json`, optional FILE   | Validates schema; warn-by-default, strict opts into raise                 |
| `praisonai config sources`         | none                                         | Prints precedence hierarchy and active layers                             |
| `praisonai config list`            | `--scope all\|user\|project`                 | Lists resolved values; verbose shows sources                              |
| `praisonai config get KEY`         | dotted path                                  | e.g. `agent.model`                                                        |
| `praisonai config set KEY VALUE`   | `--scope user\|project`                      | Writes YAML (`0600` user, `0644` project)                                 |
| `praisonai config reset`           | `--scope user\|project`, `-y`                | Deletes corresponding `config.yaml`                                       |
| `praisonai config path`            | `--scope user\|project`                      | Shows config file path and existence                                      |
| `praisonai config env`             | `--scope`, `--validate`                      | Registered env vars and validation                                        |
| `praisonai config doctor`          | none                                         | Configuration diagnostics                                                 |

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Verify resolution
praisonai config show --sources
# Shows sources: defaults, project:/path/to/repo/.praisonai/config.yaml, ...
```

***

## Backward Compatibility

<AccordionGroup>
  <Accordion title="Legacy ~/.praison/config.toml">
    Still read on startup if no YAML config exists. RAG and model keys are migrated to the new `agent.*` / `rag.*` schema automatically.
  </Accordion>

  <Accordion title="Legacy ~/.praisonai/.env">
    Model and provider keys from `.env` are merged into the resolved config when no YAML is present.
  </Accordion>

  <Accordion title="Project .praison/config.toml">
    Walk-up discovery still finds legacy TOML project configs and migrates them on read.
  </Accordion>
</AccordionGroup>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Pin model per project">
    Commit `.praisonai/config.yaml` to your repo so teammates get the same defaults.
  </Accordion>

  <Accordion title="Keep secrets out of YAML">
    `api_key` is never serialised; use env vars or `praisonai auth`.
  </Accordion>

  <Accordion title="Use config sources to debug">
    When behaviour surprises you, `praisonai config sources` prints exactly which layer won.
  </Accordion>

  <Accordion title="Walk-up means subdirectories inherit">
    Running `praisonai` from `repo/scripts/` finds `repo/.praisonai/config.yaml`.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Config CLI Reference" icon="terminal" href="/docs/cli/config">
    Full subcommand reference for `praisonai config`
  </Card>

  <Card title="Configuration Index" icon="settings" href="/configuration">
    SDK-level agents, tasks, and memory configuration
  </Card>

  <Card title="Runtime Selection" icon="play" href="/docs/features/runtime-selection">
    Model-scoped runtime configuration
  </Card>

  <Card title="LLM Endpoint Config" icon="link" href="/docs/features/llm-endpoint-config">
    Custom base URLs and provider routing
  </Card>

  <Card title="Single-Source Config" icon="gear" href="/docs/features/single-source-config">
    Model + MCP + permissions in one file
  </Card>
</CardGroup>