Init

Scaffold the .praisonai/ project convention in one command

praisonai init creates a working .praisonai/ project — config, a starter agent, a starter command, and a starter tool — so the next commands you type already run.

Quick Start

1. Scaffold the project

   praisonai init
   

   This writes four 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

Step	What happens
Resolve target	Walks up to the git root (or uses cwd) and sets .praisonai/ as the base
Write files	Creates config.yaml, agents/assistant.md, commands/review.md, tools/example.py
Report	Prints Created <path> or Skipped (already exists, use --force): <path> per file
Next steps	Prints the exact praisonai run --agent and praisonai run --command commands you can copy, plus a one-line hint that project-local tools are opt-in

Project vs global

Flags

Flag	Type	Default	Description
--global	bool	False	Scaffold the user-global ~/.praisonai/ instead of the project directory
--force / -f	bool	False	Overwrite 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

tools/example.py — commented @tool starter, auto-discovered on run:

"""Project-local tools for this .praisonai/ project.

Every public callable in this directory is made available to the agent on
`praisonai run` — no --tools flag required. Decorate a function with @tool for
a rich schema, or just define a plain function.

Loading executes this file, so it is OPT-IN. Enable it on `run` with either:

    praisonai run --allow-local-tools "use the greet tool to greet Ada"
    # or: export PRAISONAI_ALLOW_LOCAL_TOOLS=true

Without the opt-in, `run` prints a one-line hint (it never silently skips).
Uncomment the example below to try it.
"""

# from praisonaiagents import tool
#
#
# @tool
# def greet(name: str) -> str:
#     """Return a friendly greeting for the given name."""
#     return f"Hello, {name}!"

Uncomment the stub and pass --allow-local-tools (or set PRAISONAI_ALLOW_LOCAL_TOOLS=true), then every praisonai run in this project auto-loads example.greet. See Project-local tools for discovery and safety rules.

After a successful praisonai init, the CLI also prints a one-line opt-in reminder:

Project-local tools are opt-in — add --allow-local-tools (or set PRAISONAI_ALLOW_LOCAL_TOOLS=true) to load .praisonai/tools/*.py.

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

Commit .praisonai/ to git

Check in .praisonai/agents/, .praisonai/commands/, and .praisonai/tools/ so the whole team shares the same agents, commands, and tools without any extra setup. Project-local tools still require each teammate to pass --allow-local-tools (or set PRAISONAI_ALLOW_LOCAL_TOOLS=true) before they auto-load.

Keep ~/.praisonai/ personal

Use --global for shortcuts that are specific to you. Team-shared agents belong in the project directory — project files override global on name collision.

Edit the starter files, don't replace them

The scaffolded files match the exact shape CustomDefinitionsDiscovery parses: frontmatter fields for agents, $ARGUMENTS / @file substitutions for commands. Keep that structure when customising.

Use --force carefully

--force overwrites existing files without prompting. Commit or back up your edits first.

Related

Custom Agents, Commands & Tools

Agent frontmatter, command templates, and project-local tool discovery

Agent CLI

List and inspect custom agents

Command CLI

List and preview custom commands

Config CLI

Manage project and global configuration