Skip to main content
The praisonai CLI reads .praison.json from your project — and finds it automatically even when you run the CLI from a deep subdirectory. 
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful.")
agent.start("Summarise the README")
The user runs the agent from any subdirectory; hierarchical config supplies merged settings.

​
Precedence

​
Quick Start

1

Drop .praison.json in your project root

{
  "model": "gpt-4o-mini",
  "temperature": 0.3
}
2

Use an agent from anywhere inside the repo

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful.")
agent.start("Summarise the README")
The CLI discovers .praison.json automatically — no extra setup needed, even if you’re nested deep inside repo/src/deep/pkg/.
3

Verify what got merged

from praisonai.cli.features.config_hierarchy import load_config

print(load_config())

​
How Walk-up Works

  • Starts at project_dir (defaults to os.getcwd()).
  • At every level, checks .praison.json then praison.json (in that precedence order).
  • Stops at a directory containing .git — config never leaks across project boundaries.
  • When no .git is ever found, caps the walk at 10 ancestor levels to avoid accidentally picking up unrelated configs.
  • Nearest config wins — the first hit is returned.

​
Choose Your Mode

Default walk-up (recommended): 
from praisonai.cli.features.config_hierarchy import HierarchicalConfig

config = HierarchicalConfig()
settings = config.load()
Disable walk-up (cwd only): 
config = HierarchicalConfig(walk_up=False)
settings = config.load()
Explicit starting directory: 
config = HierarchicalConfig(project_dir="/path/to/project")
settings = config.load()

​
Walk-up Boundaries

The walk stops when it hits either:
  • A directory containing .git (inclusive — the git-root itself is still checked for configs).
  • 10 ancestor levels without finding any .git marker.

​
Configuration File Precedence

LayerPathNotes
Project (hidden).praison.json (walk-up from cwd)Checked first at each level
Project (visible)praison.json (walk-up from cwd)Fallback at each level
User~/.config/praison/praison.json—
Global/etc/praison/praison.json—

​
Configuration Schema

Top-level keys supported in .praison.json:
KeyTypeDescription
modelstringLLM model name (e.g. "gpt-4o")
temperaturenumberSampling temperature (0–2)
max_tokensintegerMax tokens per response
providersobjectProvider-specific settings (api_key, base_url)
mcpobjectMCP server configuration
permissionsobjectTool and path allowlists
lspobjectLanguage server protocol settings
outputobjectOutput mode and color settings
attributionobjectGit commit attribution style
Example .praison.json: 
{
  "model": "gpt-4o",
  "temperature": 0.7,
  "permissions": {
    "allowed_tools": ["read_file", "write_file"],
    "allowed_paths": ["./src", "./tests"]
  },
  "output": {
    "mode": "compact",
    "color": true
  }
}

​
Common Patterns

Monorepo with per-package overrides: Place a root .praison.json with your default model, then add a packages/frontend/.praison.json for package-specific overrides: 
// packages/frontend/.praison.json
{
  "model": "gpt-4o",
  "temperature": 0.1
}
Running praisonai run "..." from inside packages/frontend/ picks up the nearest config automatically. Pin model and permissions for the whole repo: A single .praison.json at the repo root applies to every subdirectory: 
{
  "model": "gpt-4o-mini",
  "permissions": {
    "allowed_tools": ["read_file"],
    "allowed_paths": ["./src"]
  }
}
Test fixture isolation: 
from praisonai.cli.features.config_hierarchy import HierarchicalConfig

def test_my_feature(tmp_path):
    config = HierarchicalConfig(project_dir=str(tmp_path), walk_up=False)
    settings = config.load()

​
Constructor Parameters

ParamTypeDefaultDescription
project_dirstros.getcwd()Starting directory for project-config discovery.
user_configstr~/.config/praison/praison.jsonPath to the user-level config file.
global_configstr/etc/praison/praison.jsonPath to the global config file.
walk_upboolTrueWhen True, walk parent dirs to the git root (capped at 10 levels without a .git). When False, only check project_dir.
Most users never need to import HierarchicalConfig directly — the CLI picks up .praison.json automatically. Use the import only when you need programmatic access or test isolation.

​
Best Practices

Every teammate gets the same model and permissions automatically — no manual setup, no environment drift.
.praison.json (hidden) is for project-default state checked in to version control. Reserve praison.json (visible) for local human-editable overrides you want to keep out of git.
Provider api_key values in .praison.json get committed to git. Store credentials in environment variables or a secrets manager instead.
Pass walk_up=False (or set an explicit project_dir to an isolated tmp_path) so tests do not inherit ancestor .praison.json files and become order-dependent or environment-sensitive.
Running the CLI from a subdir of an unrelated parent repo will not pull in that parent’s config. The .git marker is the safety boundary.

YAML CLI Configuration

.praisonai/config.yaml — a separate YAML-based config system, not affected by walk-up discovery.

Advanced Features

Other advanced CLI features including safe shell, file history, and output modes.

praisonai config subcommand

Reference for the praisonai config command (YAML system).

Context Files

Walk-up discovery for AGENTS.md / CLAUDE.md — the same boundary pattern applied to context files.