.env File Loading

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

Quick Start

Simple Usage

Create a .env next to where you run PraisonAI:

# .env
OPENAI_API_KEY=sk-...

Run an agent file from that directory:

from praisonaiagents import Agent

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

praisonai run "hello"

With Configuration

praisonai.api.call does not read .env on import. Opt in with an environment variable:

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.

How It Works

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

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?

For library use:

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

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.

Best Practices

Put .env in your project root

Keep it in the directory you run praisonai from, so the CLI always finds it.

Never commit .env

Add .env to .gitignore so keys stay out of version control.

Prefer shell exports for secrets in CI

.env is a developer convenience, not a secrets manager. Export variables from your CI secret store instead.

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.

Security Environment Variables

Environment-variable gates and security advisories

PraisonAI Call

Voice call server and its environment variables

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

How It Works

Which Entry Points Auto-Load `.env`

Do I Need to Load `.env` Manually?

Precedence

Best Practices

Security Environment Variables

PraisonAI Call

​Quick Start

​How It Works

​Which Entry Points Auto-Load .env

​Do I Need to Load .env Manually?

​Precedence

​Best Practices

​Related

Security Environment Variables

PraisonAI Call

Quick Start

How It Works

Which Entry Points Auto-Load `.env`

Do I Need to Load `.env` Manually?

Precedence

Best Practices

Related