Context

Upstream PR MervinPraison/PraisonAI#1545 (merged 2026-04-24) fixes a UnicodeEncodeError that crashed praisonai --help and other Rich/Typer-rendered CLI output on Windows terminals running a legacy code page (CP1252, CP1251, CP850, ASCII). Fixes #1543.

The fix is automatic — users do not need to configure anything — but the behavior and fallback path are currently undocumented. Searching the entire docs/ tree for UnicodeEncodeError, PYTHONIOENCODING, cp1252, or legacy_windows returns zero matches, and docs/installation.mdx (Windows tab) has no note about terminal encoding. Users who hit the old crash, or who are still running older versions, have no reference to point them at.

This issue tracks the doc work needed to close that gap.

Scope of the upstream change

Files changed in PraisonAI PR #1545:

What this means for users:

• praisonai --help (and all CLI output) now works on Windows CMD / PowerShell with default code pages.
• Rich boxes/colors/emojis are automatically downgraded to ASCII-safe output when needed.
• If encoding still fails, the CLI prints a hint: Try setting: $env:PYTHONIOENCODING='utf-8' (PowerShell) or set PYTHONIOENCODING=utf-8 (cmd).

No new public APIs, no new agent parameters, no config dataclass. This is a CLI/platform reliability fix — so the doc work is user-focused (troubleshooting + install notes), not SDK reference.

Recommendation: update existing content, do not create a docs/concepts/ page

Per AGENTS.md rules, docs/concepts/ is human-only. This change is not a conceptual feature — it's a platform/CLI note. All updates below belong in docs/installation.mdx, docs/install/, docs/cli/, and/or docs/guides/.

Required doc changes

1. Update docs/installation.mdx — Windows tab

Add a short note at the end of the Windows install steps (or as a <Tip> / <Note> callout) explaining that the CLI auto-handles legacy Windows code pages, and how to force UTF-8 if users want full emoji/box-drawing output.

Suggested content (user-focused, concise, per AGENTS.md style rules):

<Note>
**Windows terminals:** PraisonAI automatically detects legacy Windows code pages (CP1252, CP850, etc.) and falls back to ASCII-safe output. For full emoji and box-drawing rendering, switch your terminal to UTF-8:

<CodeGroup>
```powershell PowerShell
$env:PYTHONIOENCODING='utf-8'
chcp 65001

set PYTHONIOENCODING=utf-8
chcp 65001

2. Add a Windows troubleshooting entry

There is no CLI troubleshooting page today. The only troubleshooting files are docs/guides/troubleshoot-gateway.mdx and docs/examples/agent-recipes/troubleshooting.mdx, neither of which covers CLI/platform issues.

Option A (preferred): add a new page docs/guides/windows-terminal-encoding.mdx covering:

• Symptom: UnicodeEncodeError: 'charmap' codec can't encode character when running praisonai --help or any CLI command.
• Root cause: Windows legacy code page (CP1252/CP1251/CP850/ASCII) cannot render Rich's Unicode box-drawing characters or emoji.
• Automatic mitigation: PraisonAI ≥ (release containing PR #1545) detects this and renders ASCII-safe output automatically.
• Manual override (for older versions or full UTF-8 rendering):
  • PowerShell: $env:PYTHONIOENCODING='utf-8' then chcp 65001
  • CMD: set PYTHONIOENCODING=utf-8 then chcp 65001
  • Permanent: set PYTHONIOENCODING in System → Environment Variables
• When to use Windows Terminal / WSL instead for best experience.

Option B: add the same content as a section inside an existing CLI page (e.g. docs/cli/cli-reference.mdx or docs/cli/cli.mdx). Option A is cleaner because the page is discoverable via search for "Windows encoding".

3. Register the new page in docs.json

If Option A is chosen, add the new page under the "Guides" group (never under "Concepts"). Do not touch auto-generated docs/js/ or docs/rust/ entries. Verify docs.json is valid JSON after editing.

4. Mermaid diagram (per AGENTS.md §3)

Include a small decision-flow diagram at the top of the new page showing how the CLI chooses output mode. Use the standard color palette:

graph TB
    Start[praisonai --help] --> Detect{Windows +<br/>legacy code page?}
    Detect -->|No| Rich[Full Rich output<br/>emoji + box drawing]
    Detect -->|Yes| Safe[Safe Console<br/>ASCII box, no emoji]
    Safe --> Fallback{Still<br/>UnicodeEncodeError?}
    Fallback -->|No| Safe
    Fallback -->|Yes| Hint[Print remediation:<br/>set PYTHONIOENCODING=utf-8]

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff
    classDef warning fill:#8B0000,stroke:#7C90A0,color:#fff

    class Start input
    class Detect,Fallback decision
    class Rich,Safe success
    class Hint warning

5. Page frontmatter (if Option A)

---
title: "Windows Terminal Encoding"
sidebarTitle: "Windows Encoding"
description: "Fix UnicodeEncodeError on Windows CMD/PowerShell and get full Rich output"
icon: "terminal"
---

Out of scope / not needed

• ❌ No SDK reference pages (no new classes/params).
• ❌ No changes to docs/concepts/ (human-only per AGENTS.md).
• ❌ No changes to docs/js/ or docs/rust/ (auto-generated).
• ❌ No code samples using Agent(...) — this is a CLI/platform note, not an agent feature.

Acceptance criteria

• docs/installation.mdx Windows tab includes a <Note> about auto-fallback and how to enable full UTF-8.
• New page docs/guides/windows-terminal-encoding.mdx exists (or equivalent section added to an existing CLI page) with: symptom, root cause, automatic mitigation, manual override (PowerShell + CMD + permanent env var), Mermaid decision diagram.
• Page is registered in docs.json under a non-Concepts group, and docs.json is valid JSON.
• Search for UnicodeEncodeError or PYTHONIOENCODING in the docs returns a hit.
• Follows AGENTS.md style: one-sentence section intros, active voice, no forbidden phrases, correct Mermaid color palette.

References

• Upstream PR: fix: Windows Unicode encoding error in CLI help command (fixes #1543) PraisonAI#1545
• Upstream issue: praisonai --help crashes on Windows with Unicode encoding error PraisonAI#1543
• Changed files:
  • src/praisonai/praisonai/__main__.py
  • src/praisonai/praisonai/cli/output/console.py

🤖 Filed automatically by the docs-sync agent in response to PR #1545 merge.