> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "praisonai init"
I[⚡ praisonai init] --> S[📁 .praisonai/]
S --> C[📝 config.yaml]
S --> A[🤖 agents/assistant.md]
S --> CMD[🛠 commands/review.md]
S --> TL[🔧 tools/example.py]
end
classDef cmd fill:#6366F1,stroke:#7C90A0,color:#fff
classDef dir fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef file fill:#10B981,stroke:#7C90A0,color:#fff
class I cmd
class S dir
class C,A,CMD,TL file
```
## Quick Start
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai init
```
This writes four files under `.praisonai/` — skipping any that already exist.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai run --agent assistant "hello"
```
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai run --command review "src/foo.py"
```
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant CLI as praisonai init
participant FS as File system
User->>CLI: praisonai init
CLI->>FS: Resolve target (git root or cwd)
CLI->>FS: Write config.yaml / agents/ / commands/ / tools/
FS-->>CLI: Created / Skipped per file
CLI-->>User: Next-step commands
```
| 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 ` or `Skipped (already exists, use --force): ` 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
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q{Where should agents/commands live?}
Q -->|Share with the team via git| P[praisonai init]
Q -->|Personal across all projects| G[praisonai init --global]
P --> PD[./.praisonai/]
G --> GD[~/.praisonai/]
classDef pick fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef cmd fill:#6366F1,stroke:#7C90A0,color:#fff
classDef dir fill:#10B981,stroke:#7C90A0,color:#fff
class Q pick
class P,G cmd
class PD,GD dir
```
## 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](/docs/models#provider-auto-detection-no-config-first-run) 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](/docs/models#provider-auto-detection-no-config-first-run) for the full precedence.
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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.
```markdown theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
---
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`:
```markdown theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
---
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`:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
"""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](/docs/features/custom-agents-commands#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
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai init --force
```
### Set up personal shortcuts
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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/`, `.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.
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.
## Related
Agent frontmatter, command templates, and project-local tool discovery
List and inspect custom agents
List and preview custom commands
Manage project and global configuration