Skip to main content
praisonai init creates a working .praisonai/ project — config, a starter agent, and a starter command — so the next two commands you type already run.

​
Quick Start

1

Scaffold the project

praisonai init
This writes three files under .praisonai/ — skipping any that already exist.
2

Run the scaffolded agent

praisonai run --agent assistant "hello"
3

Run the scaffolded command

praisonai run --command review "src/foo.py"

​
How It Works

StepWhat happens
Resolve targetWalks up to the git root (or uses cwd) and sets .praisonai/ as the base
Write filesCreates config.yaml, agents/assistant.md, commands/review.md
ReportPrints Created <path> or Skipped (already exists, use --force): <path> per file
Next stepsPrints the exact praisonai run --agent and praisonai run --command commands you can copy

​
Project vs global

​
Flags

FlagTypeDefaultDescription
--globalboolFalseScaffold the user-global ~/.praisonai/ instead of the project directory
--force / -fboolFalseOverwrite existing files (otherwise existing files are skipped)

​
Scaffolded files

​
Scaffolded model is provider-aware

praisonai init reads your available provider credentials (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY, COHERE_API_KEY, OLLAMA_HOST) and writes the matching default model into both config.yaml and agents/assistant.md. Falls back to gpt-4o-mini when no credential is detected. This choice is not persisted as your recent model — subsequent praisonai run invocations resolve independently. See Models → Provider Auto-Detection for the full credential-to-model precedence table. config.yaml — project-wide defaults:
The model: value shown below (gpt-4o-mini) is the terminal fallback. With only ANTHROPIC_API_KEY set, the scaffolded model: is anthropic/claude-3-5-sonnet-latest; with only GEMINI_API_KEY, it is gemini/gemini-1.5-flash. See Models → Provider Auto-Detection for the full precedence.
# yaml-language-server: $schema=https://raw.githubusercontent.com/MervinPraison/PraisonAI/main/src/praisonai/praisonai/cli/configuration/config.schema.json
# PraisonAI project configuration
# Defaults applied to scaffolded agents and commands.
# Sections are nested exactly as the resolver consumes them.
agent:
  model: gpt-4o-mini
output:
  format: text
The # yaml-language-server: line enables editor autocomplete and inline error highlighting in VS Code (YAML extension) and other LSP-aware editors. The nested agent: / output: shape is exactly what ConfigResolver reads — flat top-level model: / output: keys will now produce a warning. agents/assistant.md — ready-to-run starter agent:
The model: field is written with the provider-detected default (same logic as config.yaml above). The value shown here is the terminal fallback.
---
model: gpt-4o-mini
role: Assistant
goal: Help the user accomplish tasks accurately and concisely
instructions: |
  You are a helpful assistant. Answer clearly and concisely.
  When you are unsure, say so instead of guessing.
---
You are a helpful assistant for this project.

Be concise, accurate, and practical. Prefer actionable answers.
commands/review.md — starter command using $ARGUMENTS and @file: 
---
description: Review the provided code or file and suggest improvements
---
Review the following and suggest concrete improvements
(correctness, readability, performance, and security):

$ARGUMENTS

If a file path is provided, here are its contents:

@$ARGUMENTS

​
Common Patterns

​
Scaffold a fresh project

praisonai init
praisonai run --agent assistant "hello"

​
Re-init after editing a file

praisonai init is idempotent — it skips files that already exist. To overwrite with the original starters: 
praisonai init --force

​
Set up personal shortcuts

praisonai init --global
Agents and commands land in ~/.praisonai/ and are available in every project. Project-level definitions override global ones on name collision.

​
Best Practices

Check in .praisonai/agents/ and .praisonai/commands/ so the whole team shares the same agents and commands without any extra setup.
Use --global for shortcuts that are specific to you. Team-shared agents belong in the project directory — project files override global on name collision.
The scaffolded files match the exact shape CustomDefinitionsDiscovery parses: frontmatter fields for agents, $ARGUMENTS / @file substitutions for commands. Keep that structure when customising.
--force overwrites existing files without prompting. Commit or back up your edits first.

Custom Agents & Commands

Agent frontmatter fields, command template syntax, and discovery rules

Agent CLI

List and inspect custom agents

Command CLI

List and preview custom commands

Config CLI

Manage project and global configuration