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.

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.

Quick Start

1. Set a default model

   praisonai config set agent.model gpt-4o-mini
   
2. Run any agent

   praisonai run "Summarise this README"
   

   The model from config is picked automatically — no --model flag needed.

3. Inspect what was resolved

   praisonai config show --sources
   

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

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

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)

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

# 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

---

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

api_key is never serialised to YAML — use environment variables or praisonai auth.

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:

# .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 for a full guide to using all three sections together. Other top-level sections (output, traces, session) are also valid — see Config CLI reference.

---

Validation

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

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.

---

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

# Verify resolution
praisonai config show --sources
# Shows sources: defaults, project:/path/to/repo/.praisonai/config.yaml, ...

---

Backward Compatibility

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.

Legacy ~/.praisonai/.env

Model and provider keys from .env are merged into the resolved config when no YAML is present.

Project .praison/config.toml

Walk-up discovery still finds legacy TOML project configs and migrates them on read.

---

Best Practices

Pin model per project

Commit .praisonai/config.yaml to your repo so teammates get the same defaults.

Keep secrets out of YAML

api_key is never serialised; use env vars or praisonai auth.

Use config sources to debug

When behaviour surprises you, praisonai config sources prints exactly which layer won.

Walk-up means subdirectories inherit

Running praisonai from repo/scripts/ finds repo/.praisonai/config.yaml.

---

Interpolation & Provenance

Any config value can reference ${VAR}, {env:NAME:-default}, or {file:./relative/path} — see Value Interpolation for the directive table and its security rules.

Run praisonai config provenance to see the winning value of each key and the exact layer/file that supplied it — see provenance.

---

Related

Config CLI Reference

Full subcommand reference for praisonai config

Configuration Index

SDK-level agents, tasks, and memory configuration

Runtime Selection

Model-scoped runtime configuration

LLM Endpoint Config

Custom base URLs and provider routing

Single-Source Config

Model + MCP + permissions in one file