Skip to main content
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.
LayerSourcePrecedence
1Built-in defaultsLowest
2Global ~/.praisonai/config.yaml (+ legacy paths)
3Project config (walk-up to git root)
4Environment variables
5CLI flagsHighest

Project vs Global Config

LocationScopeCommit to repo?
~/.praisonai/config.yamlAll projects on this machineNo
./.praisonai/config.yamlThis project (and subdirectories)Yes
./praison.yaml / ./praison.ymlAlternative project namesYes
./.praison/config.tomlLegacy 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

KeyTypeDefaultNotes
agent.modelstrNonee.g. gpt-4o-mini, claude-sonnet-4-6
agent.providerstrNonee.g. openai, anthropic
agent.base_urlstrNoneCustom LLM base URL
agent.toolslist[str][]Default tool names
agent.toolsetstrNoneNamed toolset
agent.default_agentstrNoneDefault agent slug
agent.memorybool or dictNoneEnable memory or config dict
agent.streamboolTrueStream responses
agent.temperaturefloat0.7LLM temperature
agent.max_tokensint16000LLM token budget
api_key is never serialised to YAML — use environment variables or praisonai auth.

mcp.servers.<name>

KeyTypeDefaultDescription
commandlist[str] or strLocal (stdio) server launch command. List form preferred.
argslist[str][]Extra args appended to command.
envdict[str, str]{}Env vars for the server process. Values containing , are skipped on the command-string path.
enabledbooltrueSet false to declare-but-not-wire a server.
type"remote"Marks a remote server; skipped by the run command-string path.
urlstrRemote endpoint; presence implies remote.

permissions.*

KeyTypeDefaultDescription
default"allow" | "deny" | "ask"Fallback action when no rule matches.
ruleslist[{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.
ModeEnable viaBehaviour 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=1All 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

VariableMaps toNotes
MODEL_NAMEagent.model
OPENAI_MODEL_NAMEagent.model
PRAISONAI_MODELagent.model
PRAISONAI_PROVIDERagent.provider
OPENAI_BASE_URLagent.base_url
OPENAI_API_BASEagent.base_url
PRAISONAI_BASE_URLagent.base_url
PRAISONAI_OUTPUT_FORMAToutput.format
PRAISONAI_COLORoutput.colorbool: true/1/yes
PRAISONAI_VERBOSEoutput.verbosebool
PRAISONAI_QUIEToutput.quietbool
PRAISONAI_TELEMETRYtelemetrybool

Subcommand Reference

CommandFlagsBehaviour
praisonai config show--format yaml|json|table, --sources/-sPrints fully resolved config; with --sources, lists contributing layers
praisonai config validate [FILE]--strict-config, --json, optional FILEValidates schema; warn-by-default, strict opts into raise
praisonai config sourcesnonePrints precedence hierarchy and active layers
praisonai config list--scope all|user|projectLists resolved values; verbose shows sources
praisonai config get KEYdotted pathe.g. agent.model
praisonai config set KEY VALUE--scope user|projectWrites YAML (0600 user, 0644 project)
praisonai config reset--scope user|project, -yDeletes corresponding config.yaml
praisonai config path--scope user|projectShows config file path and existence
praisonai config env--scope, --validateRegistered env vars and validation
praisonai config doctornoneConfiguration diagnostics
# Verify resolution
praisonai config show --sources
# Shows sources: defaults, project:/path/to/repo/.praisonai/config.yaml, ...

Backward Compatibility

Still read on startup if no YAML config exists. RAG and model keys are migrated to the new agent.* / rag.* schema automatically.
Model and provider keys from .env are merged into the resolved config when no YAML is present.
Walk-up discovery still finds legacy TOML project configs and migrates them on read.

Best Practices

Commit .praisonai/config.yaml to your repo so teammates get the same defaults.
api_key is never serialised; use env vars or praisonai auth.
When behaviour surprises you, praisonai config sources prints exactly which layer won.
Running praisonai from repo/scripts/ finds repo/.praisonai/config.yaml.

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