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.

Project vs Global Config

† When placed directly at $HOME, .praison/config.toml is loaded once as global: (never as project:).

Walk-up discovery searches, at each directory from cwd up to the git root or $HOME (whichever comes first). At $HOME the legacy .praison/config.toml name is skipped — that file is owned by the global loader:

1. .praisonai/config.yaml
2. .praisonai/config.yml
3. praisonai.yaml / praisonai.yml (canonical project-root config, added in PR #3422)
4. praison.yaml / praison.yml (legacy fallback, discovered for backward compat)
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

Walk-up Boundaries

Walk-up stops at the nearer of two boundaries: a .git-marked directory or $HOME.

• The walk stops at the nearer of a .git-marked directory or $HOME.
• $HOME itself is still searched for project configs, so ~/.praisonai/config.yaml and ~/praisonai.yaml remain discoverable.
• The legacy .praison/config.toml name is skipped only at $HOME — that file belongs to the global loader and is loaded exactly once as global:.
• A config placed above $HOME (e.g. /Users/praisonai.yaml in a shared-parent layout) no longer wins, because $HOME is now a hard boundary.
• If $HOME is unresolvable (Path.home() raises), the walk falls back to filesystem root.
• The CLI home root (sessions, traces, logs, cache, model-recency) is now the canonical ~/.praisonai/ — the same directory praisonai setup and the SDK use — unless PRAISONAI_HOME overrides it. A legacy ~/.praison/ is read-only when it is the sole directory present.

Choose Your Scope

CLI Home Root

The CLI writes everything under one directory — ~/.praisonai/ by default, or wherever PRAISONAI_HOME points. Config, sessions, traces, logs, cache, credentials, .env, and durable state all live together there.

Every user-scoped artefact resolves under the same home root:

Override with PRAISONAI_HOME

Set PRAISONAI_HOME to re-root every artefact together — config and sessions and traces and logs and cache all move as one.

export PRAISONAI_HOME=/var/lib/praisonai
praisonai config set agent.model gpt-4o-mini
# → writes /var/lib/praisonai/config.toml
# → sessions, traces, logs, cache all now live under /var/lib/praisonai/

Tilde is expanded, so PRAISONAI_HOME=~/mycustom resolves the same as PRAISONAI_HOME=$HOME/mycustom.

from praisonaiagents.paths import get_data_dir

# Both the SDK and the CLI resolve the same home root
print(get_data_dir())  # /var/lib/praisonai (or ~/.praisonai by default)

Legacy ~/.praison/ — read-only fallback

If an older install still has ~/.praison/config.toml, the CLI keeps reading it until the first write. Any praisonai config set / praisonai config reset seeds from whatever currently resolves, then writes the merged result to ~/.praisonai/config.toml — migrating legacy values forward without ever mutating the legacy file. The SDK honours the legacy directory the same way (with a deprecation warning); praisonai migrate-data moves everything to the canonical root.

Project data directory (.praisonai/)

Project-local CLI state lives in ./.praisonai/ — the same directory the runtime (praisonaiagents.paths) reads from. Everything below goes through a single pair of helpers in cli/configuration/paths.py, derived from the one constant PROJECT_DATA_DIRNAME (itself praisonaiagents.paths.DEFAULT_DIR_NAME), so a new site cannot drift:

• get_project_data_path(...) — the canonical write path (<cwd>/.praisonai/<file>).
• resolve_project_data_path(...) — the read path: returns the canonical file if it exists, else an existing legacy <cwd>/.praison/<file>, else the canonical path.

Files written under ./.praisonai/

These nine (plus one) project-data sites migrated from ./.praison/ (or ~/.praison/) to the canonical ./.praisonai/ in PR #4946. A read-only fallback to .praison/ is preserved so nothing saved earlier is orphaned:

Configuration Schema

agent.* defaults

mcp.servers.<name>

permissions.*

instructions

Top-level list of extra instruction/context sources loaded alongside the convention-only AGENTS.md / CLAUDE.md auto-discovery. List values concatenate across the config hierarchy (global → user → project), so a project extends rather than replaces the org-wide list.

# .praisonai/config.yaml
instructions:
  - docs/standards/python.md
  - docs/standards/security.md
  - https://example.com/rules.md

Same first-class, layerable status as agent., mcp.servers., and permissions.* — also mirrored by the repeatable praisonai run --instructions <path|glob|url> flag.

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 }

instructions:
  - docs/standards/python.md
  - https://example.com/rules.md

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.

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

Subcommand Reference

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

Backward Compatibility

Best Practices

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