Skip to main content
The config command manages layered CLI defaults — global, project, environment, and runtime flags merged into one resolved config.

Quick Start

1

Set a default model

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

Verify resolution

praisonai config show

Usage

praisonai config [OPTIONS] COMMAND [ARGS]...

Commands

CommandDescription
showShow fully resolved configuration
sourcesList configuration layers in precedence order
validate [FILE]Validate YAML syntax and schema
listList all configuration values
get KEYGet a value by dotted path (e.g. agent.model)
set KEY VALUESet a value (--scope user|project)
resetReset config to defaults (--scope user|project)
pathShow config file path
envShow registered environment variables
doctorRun configuration diagnostics

show

praisonai config show                          # YAML (default)
praisonai config show --format json            # JSON output
praisonai config show --format table           # Flat key=value table
praisonai config show --sources                # Include contributing layers
When mcp or permissions are set in any config layer, praisonai config show includes those sections in the output.

validate

Validates discovered config files against the schema, catching typos with difflib-based suggestions.
praisonai config validate                          # Validate discovered configs (warn-by-default)
praisonai config validate .praisonai/config.yaml   # Validate a specific file
praisonai config validate --strict-config          # Treat warnings as errors (exit 1)
praisonai config validate --json                   # Machine-readable output
Example output for a typo:
⚠ Unknown config key 'temprature' in .praisonai/config.yaml (section: agent). Did you mean 'temperature'?
⚠ Configuration loaded with 1 warning(s).
ℹ Use --strict-config (or PRAISONAI_STRICT_CONFIG=1) to fail on these.
FlagTypeDefaultBehaviour
--strict-config / --strictboolFalseTreat unknown/typo keys as errors (exit 1)
--jsonboolFalseEmit {valid, warnings, sources, hint} JSON

sources

praisonai config sources
Prints the five-layer hierarchy and which global/project/env sources are currently active.

set / get / reset / path

praisonai config set agent.model gpt-4o-mini
praisonai config set agent.temperature 0.3 --scope project
praisonai config get agent.model
praisonai config reset --scope project -y
praisonai config path --scope user
ScopeFilePermissions
user (default)~/.praisonai/config.yaml0600
project./.praisonai/config.yaml0644

Strict Validation

Unknown or mistyped keys are reported with the closest valid match. By default they are warnings — your valid keys still apply. Opt into strict mode to fail-fast.
ModeTriggerBehaviour
Warn (default)Logs UserWarning per unknown key, run continues
Strict (per-call)--strict-config on config validate or ConfigResolver(strict=True)Raises ValueError on first unknown key
Strict (global)PRAISONAI_STRICT_CONFIG=1 env varAll resolver calls run in strict mode
# Catch typos in CI:
PRAISONAI_STRICT_CONFIG=1 praisonai config validate

# Or per-call:
praisonai config validate --strict-config
The validator inspects the raw discovered config (before normalisation through ResolvedConfig), so nested mistakes like agent.temprature surface instead of being silently dropped.

Configuration File

Primary format is YAML at ~/.praisonai/config.yaml (global) or ./.praisonai/config.yaml (project):
agent:
  model: gpt-4o-mini
  temperature: 0.7
  max_tokens: 16000
  stream: true

mcp:
  servers:
    playwright:
      command: ["npx", "-y", "@playwright/mcp"]

permissions:
  default: ask
  rules:
    - { pattern: "bash:git *", action: allow }
    - { pattern: "bash:rm *",  action: deny }

output:
  verbose: false
  color: true

telemetry: true
Model lives under agent.model, not at the top level. See CLI Configuration for the full schema.

Project discovery

From cwd, the resolver walks up to the git root searching:
  1. .praisonai/config.yaml
  2. .praisonai/config.yml
  3. praison.yaml / praison.yml
  4. .praison/config.toml (legacy)

agent.* Schema

KeyTypeDefaultDescription
agent.modelstrDefault model; if unset, resolved via the provider-aware ladder rather than a hardcoded OpenAI default
agent.providerstrProvider name
agent.base_urlstrCustom API base URL
agent.toolslist[str][]Default tool names
agent.toolsetstrNamed toolset
agent.default_agentstrDefault agent slug
agent.memorybool/dictMemory config
agent.streambooltrueStream responses
agent.temperaturefloat0.7Sampling temperature
agent.max_tokensint16000Max output tokens
Store API keys via env vars or praisonai authapi_key is never written to YAML.
Editor autocomplete: praisonai init writes a # yaml-language-server: $schema=... pointer to config.schema.json. VS Code (YAML extension) and other LSP editors validate against the published schema.

mcp.servers.<name> Schema

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.
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.* Schema

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.

Environment Variables

VariableMaps to
MODEL_NAME / OPENAI_MODEL_NAME / PRAISONAI_MODELagent.model
PRAISONAI_PROVIDERagent.provider
OPENAI_BASE_URL / OPENAI_API_BASE / PRAISONAI_BASE_URLagent.base_url
PRAISONAI_OUTPUT_FORMAToutput.format
PRAISONAI_COLORoutput.color
PRAISONAI_VERBOSEoutput.verbose
PRAISONAI_QUIEToutput.quiet
PRAISONAI_TELEMETRYtelemetry
OPENAI_API_KEY / ANTHROPIC_API_KEYSecrets (env only)

Legacy Formats

Legacy paths still work and are migrated on read:
PathStatus
~/.praison/config.tomlRead if no YAML; migrated to agent.* / rag.*
~/.praisonai/.envMerged for model/provider when no YAML
.praison/config.toml (project)Found via walk-up discovery
TOML [rules], [output], [mcp], [traces], and [session] sections remain valid in legacy files. New projects should use YAML.

See Also