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

Project vs global

Flags

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:

# 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:

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

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

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).

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

Related