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

# .env File Loading

> Where PraisonAI looks for your .env file and how precedence works

PraisonAI auto-loads a `.env` from your current working directory before running any CLI command.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    CWD[📁 Current directory] --> Found{🔍 .env found?}
    Found -->|Yes| Load[⚙️ load into env]
    Found -->|No, walk up| Parent{🔍 parent has .env?}
    Parent -->|Yes| Load
    Parent -->|No| None[🚫 Nothing loaded]
    Load --> Agent[✅ Agent sees keys]

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

    class CWD input
    class Found,Parent check
    class Load process
    class Agent ok
    class None bad
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    Create a `.env` next to where you run PraisonAI:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # .env
    OPENAI_API_KEY=sk-...
    ```

    Run an agent file from that directory:

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

    agent = Agent(name="Helper", instructions="You are a helpful assistant")
    agent.start("hello")
    ```

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai run "hello"
    ```
  </Step>

  <Step title="With Configuration">
    `praisonai.api.call` does not read `.env` on import. Opt in with an environment variable:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export PRAISONAI_CALL_LOAD_DOTENV=true
    python -c "import praisonai.api.call"
    ```

    The `praisonai call` CLI always loads `.env` from the current directory, no flag needed.
  </Step>
</Steps>

***

## How It Works

The CLI searches upward from where you run it, never from where PraisonAI is installed.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant You
    participant CLI as praisonai CLI
    participant Dotenv as find_dotenv(usecwd=True)
    participant Env as os.environ
    participant Agent

    You->>CLI: praisonai run "hello" (in cwd/)
    CLI->>Dotenv: search from cwd upward
    Dotenv-->>CLI: first .env found
    CLI->>Env: load, override=False
    Env-->>Agent: merged environment
```

***

## Which Entry Points Auto-Load `.env`

Each CLI entry point loads `.env` from the current directory; library imports never do.

| Entry point | Loads `.env` from CWD? | Notes |
| - | - | - |
| `praisonai run` / `praisonai chat` / `praisonai code` / direct prompt | Yes | via `_load_env_once()` on CLI startup |
| `praisonai call` CLI | Yes | explicit load in `main()` |
| `praisonai bot` | Yes | via `BotHandler._load_dotenv` |
| `import praisonai.api.call` (module import) | No | opt in with `PRAISONAI_CALL_LOAD_DOTENV=true` |
| `from praisonaiagents import Agent` (library import) | No | library imports never mutate `os.environ`; call `load_dotenv()` yourself |

***

## Do I Need to Load `.env` Manually?

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q{Do I need to load .env manually?}
    Q -->|Using the praisonai CLI| CLI[✅ No — automatic from CWD]
    Q -->|Importing praisonaiagents| Lib[📝 Yes — call load_dotenv]
    Q -->|Importing praisonai.api.call| Call[⚙️ Set PRAISONAI_CALL_LOAD_DOTENV=true]

    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
    classDef manual fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef config fill:#6366F1,stroke:#7C90A0,color:#fff

    class Q decision
    class CLI ok
    class Lib manual
    class Call config
```

For library use:

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

load_dotenv()

agent = Agent(name="Helper", instructions="You are a helpful assistant")
agent.start("hello")
```

***

## Precedence

Loading never overrides a variable that is already set (`override=False`).

| Source | Wins over | Example |
| - | - | - |
| Already-exported shell env var | `.env` | `export OPENAI_API_KEY=sk-shell` beats a `.env` value |
| `.env` in CWD | `.env` higher up the tree | `./.env` is read; `../.env` is not |
| Any `.env` above the install prefix | — | Never loaded, by design |

<Warning>
  Before this release, PraisonAI's CLIs could load a `.env` from a source checkout or any parent of `site-packages`. If an API key stops being set after upgrading, move the `.env` into the directory you run `praisonai` from, or export the variable in your shell.
</Warning>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Put .env in your project root">
    Keep it in the directory you run `praisonai` from, so the CLI always finds it.
  </Accordion>

  <Accordion title="Never commit .env">
    Add `.env` to `.gitignore` so keys stay out of version control.
  </Accordion>

  <Accordion title="Prefer shell exports for secrets in CI">
    `.env` is a developer convenience, not a secrets manager. Export variables from your CI secret store instead.
  </Accordion>

  <Accordion title="Library imports do not touch os.environ">
    When embedding `praisonaiagents` or importing `praisonai.api.call` directly, call `from dotenv import load_dotenv; load_dotenv()` yourself. See [Python Import Safety](/docs/features/python-import-safety).
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Security Environment Variables" icon="shield" href="/docs/features/security-environment-variables">
    Environment-variable gates and security advisories
  </Card>

  <Card title="PraisonAI Call" icon="phone" href="/docs/call">
    Voice call server and its environment variables
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.