Init - PraisonAI

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.

For a multi-agent team project (agents.yaml + tasks.yaml + a Python entry point), use praisonai init team <name> instead. praisonai init (this page) scaffolds the single-agent .praisonai/ convention.

For a single agent without commands or tools, use praisonai agent create instead. For a multi-agent team, use praisonai init team.

Quick Start

Scaffold the project

praisonai init

This writes four files under .praisonai/ — skipping any that already exist.

Run the scaffolded agent

praisonai run --agent assistant "hello"

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)
`--generate` / `-g`	`bool`	`False`	Analyse the repo and generate a tailored `AGENTS.md` at the repo root using the scaffolded model. Requires a provider credential; falls back silently to the static scaffold when no credential is present or generation fails. Respects `--force` on an existing `AGENTS.md`.

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.yaml editor header

Any scaffold path that emits an agents.yaml now prepends a matching header so editors validate agent definitions immediately — no manual setup.

# yaml-language-server: $schema=https://raw.githubusercontent.com/MervinPraison/PraisonAI/main/src/praisonai/praisonai/config/agents.schema.json

The header is a plain YAML comment, so runtime parsing is unaffected. See Editor Support for full setup across VS Code, Neovim, and JetBrains IDEs. 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.

AGENTS.md generation (—generate)

praisonai init --generate runs a short analysis agent that reads a cheap snapshot of your repo and writes a tailored AGENTS.md at the repo root — so your next praisonai run starts with real project context instead of boilerplate.

# One command — scaffold + tailored AGENTS.md
praisonai init --generate

# Regenerate later after big refactors
praisonai init --generate --force

--generate only runs when a provider credential is present. With no credential, or if the agent fails, init keeps the static scaffold, writes no AGENTS.md, and still exits 0. The only non-zero exit is a write failure (permissions or disk space).

Behaviour	Detail
Credential required	Runs only when `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `GROQ_API_KEY`, `COHERE_API_KEY`, or `OLLAMA_HOST` is set
Model used	The same provider-aware `scaffold_model` written into `config.yaml` / `assistant.md`
Output location	Always the repo root (`git root` or cwd) — never `~/AGENTS.md`, even with `--global`
Non-destructive	An existing `AGENTS.md` is skipped with a warning unless `--force` is also passed
Graceful fallback	No credential or generation error → keeps the static scaffold, writes no file, exits `0`

How the agent sees your repo

The pre-scan is deliberately small so cost and tokens stay bounded:

Top-level entries — directories first, first 60 names.
Detected manifests — pyproject.toml, setup.py, setup.cfg, requirements.txt, package.json, Cargo.toml, go.mod, pom.xml, build.gradle, Makefile, Dockerfile, docker-compose.yml, tox.ini.
README head — first 1500 characters of README.md, README.rst, README.txt, or README (first match wins).

The agent never reads your whole tree — only this high-signal snapshot — which bounds token usage and cost while still capturing build/test commands and conventions.

--global changes only where the static scaffold lands (~/.praisonai/). The generated AGENTS.md always writes to the repo root, because the rules loader discovers it there on the next run.

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.

Generate a repo-tailored AGENTS.md

praisonai init --generate

Scaffolds .praisonai/ and writes a project-specific AGENTS.md the rules loader picks up automatically. Regenerate after major changes:

praisonai init --generate --force

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.PraisonAI also discovers agents and commands from existing .claude/agents/ / .claude/commands/ and .agents/agents/ / .agents/commands/ layouts, so teams that already keep definitions for another tool don’t have to copy them into .praisonai/. See Custom Agents & Commands.

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.

Prefer --generate for real projects

The tailored AGENTS.md gives agents the specific build/test/run commands and conventions on first contact — which is what the rules loader ships to every subsequent turn. Keep the flag off for empty scaffolds and demos.

Init Team

Scaffold a multi-agent AgentTeam project (agents.yaml + tasks.yaml)

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

Project AGENTS.md

How the generated AGENTS.md is auto-loaded as project context

Rules CLI

Inspect the auto-discovered instruction files agents load

Editor Support

Autocomplete and inline validation for scaffolded agents.yaml

​Quick Start

​How It Works

​Project vs global

​Flags

​Scaffolded files

​Scaffolded model is provider-aware

​agents.yaml editor header

​AGENTS.md generation (—generate)

​How the agent sees your repo

​Common Patterns

​Scaffold a fresh project

​Re-init after editing a file

​Set up personal shortcuts

​Generate a repo-tailored AGENTS.md

​Best Practices

​Related

Init Team

Custom Agents, Commands & Tools

Agent CLI

Command CLI

Config CLI

Project AGENTS.md

Rules CLI

Editor Support

Quick Start

How It Works

Project vs global

Flags

Scaffolded files

Scaffolded model is provider-aware

agents.yaml editor header

AGENTS.md generation (—generate)

How the agent sees your repo

Common Patterns

Scaffold a fresh project

Re-init after editing a file

Set up personal shortcuts

Generate a repo-tailored AGENTS.md

Best Practices

Related