Skip to content

docs: update installer pages for frictionless uv/pipx/venv install (PR #2176 in PraisonAI) #824

Closed
#827
Closed
docs: update installer pages for frictionless uv/pipx/venv install (PR #2176 in PraisonAI)#824
#827
Labels
claudeTrigger Claude Code analysisdocumentationImprovements or additions to documentation

Description

@MervinPraison
MervinPraison
opened on Jun 23, 2026

Context

PR MervinPraison/PraisonAI#2176 (merged 2026-06-23, closes issue #2173) reworks src/praisonai/scripts/install.sh from a venv-only installer into a frictionless, environment-isolated one-liner with a backend preference order of uv tool install → pipx install → venv fallback, plus shell-completion installation, a ~/.local/bin/praisonai shim for the venv fallback, and several new CLI flags / env vars.

The current docs (docs/install/installer.mdx, docs/install/quickstart.mdx, docs/installation.mdx, docs/index.mdx, docs/developers/scripts.mdx) still describe the old venv-only flow. They need to be updated so a new user landing on the docs sees the same behaviour the installer actually performs.

The SDK has changed. This issue documents what the docs need to look like so another agent can update / create the relevant pages. It is user-focused, agent-friendly, and follows AGENTS.md.

TL;DR — what changed in the installer

The installer now:

  1. Picks an isolation backend automatically (preference order): uv tool → pipx → venv fallback under ~/.praisonai/venv.
  2. Drops a praisonai shim into ~/.local/bin (for the venv backend) so the binary is on PATH without sourcing a venv.
  3. Appends PATH non-destructively to the user's shell rc inside a clearly-marked # >>> PraisonAI PATH >>> block, idempotently. Can be skipped with --no-modify-path.
  4. Offers to install shell completions (bash / zsh / fish) via the existing praisonai completion <shell> subcommand.
  5. Adds new flags: --backend, --install-dir, --no-modify-path.
  6. Adds new env vars: PRAISONAI_BACKEND, PRAISONAI_INSTALL_DIR, PRAISONAI_NO_MODIFY_PATH.
  7. Documents uvx praisonai, pipx install praisonai, and pip install praisonai as first-class power-user alternatives (no installer needed).
  8. Defaults to praisonai[all] for one-line installs (previously plain praisonai); honours PRAISONAI_EXTRAS and --extras as before.
  9. The verifier now imports via the venv python for the venv backend, and falls back to the resolved praisonai CLI for uv / pipx (whose envs are isolated from system python).

All existing flags / env vars / behaviours from before the PR are preserved (backward compatible).

What docs need to change

A. UPDATE existing pages

1. docs/install/installer.mdx — MAJOR rewrite required

Currently says: "Create Virtual Environment at ~/.praisonai/venv" → "pip install praisonaiagents" → "Setup PATH".

Replace with the three-backend flow. Suggested new structure (follow AGENTS.md section 2 page template):

  • Hero mermaid diagram — show the backend decision:

    detect_backend → [uv? → uv tool install]
               → [pipx? → pipx install]
               → [else  → venv at $INSTALL_DIR + shim into ~/.local/bin]
→ ensure_path_dir(~/.local/bin) → verify → maybe_install_completions → onboarding

    Use the standard colour scheme from AGENTS.md §3.1 (#8B0000 for agents, #189AB4 for tools, #10B981 for success, #F59E0B for amber/intermediate, #6366F1 for config).

  • "How it works" steps — replace the existing <Steps> block with the new flow:

    1. Detect OS
    2. Detect isolation backend (uv → pipx → venv) — honour PRAISONAI_BACKEND / --backend
    3. Build package spec (praisonai[all] by default, or praisonai[$EXTRAS], plus optional ==VERSION)
    4. Install via the chosen backend:
      • uv tool install --force <pkg> + uv tool update-shell
      • pipx install --force <pkg> + pipx ensurepath
      • venv: create venv at $INSTALL_DIR/venv (default ~/.praisonai/venv) → pip install → symlink ~/.local/bin/praisonai → $venv/bin/praisonai
    5. Ensure ~/.local/bin is on PATH for the current session + appended to the shell rc inside a # >>> PraisonAI PATH >>> … # <<< PraisonAI PATH <<< block (unless --no-modify-path)
    6. Verify install (venv → import praisonaiagents; uv/pipx → check resolved CLI runs)
    7. Optionally install shell completions via praisonai completion <shell>
    8. Run interactive onboarding (unchanged)

  • CLI Flags table — add the three new flags:

    Flag Description
    --backend BACKEND Force isolation backend: uv, pipx, venv (default: auto)
    --install-dir DIR Base dir for the venv fallback (default: ~/.praisonai)
    --no-modify-path Do not append a PATH block to your shell rc
    --no-venv Reworded: skip isolation entirely — install into the active environment

    Keep --version, --extras, --python, --dry-run, --no-prompt, --no-onboard, -h/--help.

  • Environment variables table — add:

    Variable Description
    PRAISONAI_BACKEND Force backend: uv / pipx / venv / system / auto
    PRAISONAI_INSTALL_DIR Base dir for the venv fallback
    PRAISONAI_NO_MODIFY_PATH Skip shell rc PATH modification (1 to enable)

    Keep existing ones.

  • New section: "Power-user alternatives (no installer needed)" — document these as first-class supported paths (do not present them as fallbacks):

    uvx praisonai "2+2"        # zero-install one-shot via uv
pipx install praisonai      # isolated persistent install
pip install praisonai       # install into the active environment

  • New section: "Shell completions" — explain that:

    • The installer offers to install completions interactively (skipped under --no-prompt, --no-onboard, --dry-run, or non-TTY).
    • Users can re-run any time with praisonai completion bash / zsh / fish.
    • Where they get written: ~/.bashrc, ~/.zshrc, ~/.config/fish/completions/praisonai.fish.
    • The installer is idempotent: it greps for _praisonai_completion / #compdef praisonai before appending for bash/zsh.

  • Uninstall section — update to mention removing the ~/.local/bin/praisonai shim and (if uv/pipx was used) uv tool uninstall praisonai / pipx uninstall praisonai.

  • Troubleshooting — add:

    • "I want to force a specific backend" → --backend pipx or PRAISONAI_BACKEND=pipx.
    • "I don't want PATH modified" → --no-modify-path or PRAISONAI_NO_MODIFY_PATH=1, then manually add ~/.local/bin to PATH.
    • "I have both uv and pipx" → installer picks uv first; override with --backend pipx.

2. docs/install/quickstart.mdx — content update

  • Update hero mermaid to show the backend selection (instead of curl → Detect OS → Install Python → Create venv → pip install → Ready, show curl → Detect backend → uv/pipx/venv → Shim into ~/.local/bin → Ready). Standard colour scheme.
  • Under the existing "One-Liner Install" <Tabs>, add new tabs / sub-options:
    • uvx (zero-install one-shot): uvx praisonai "2+2"
    • pipx: pipx install praisonai
  • Update "What Gets Installed" table to include "Isolation backend (uv tool, pipx, or venv at $INSTALL_DIR)" and "~/.local/bin/praisonai shim".
  • Add accordions under "Install Options" for the new flags:
    • "Force a specific backend" → --backend pipx
    • "Custom install dir" → --install-dir /opt/praisonai
    • "Don't modify PATH" → --no-modify-path
  • Append the new env vars (PRAISONAI_BACKEND, PRAISONAI_INSTALL_DIR, PRAISONAI_NO_MODIFY_PATH) to the env vars table.

3. docs/installation.mdx

  • Reference the new installer.mdx content. Keep the one-liner as the headline path.
  • Add a one-line note that the install is isolated by default (uv/pipx/venv) and ends up shimmed under ~/.local/bin.

4. docs/index.mdx

  • The macOS / Linux / WSL2 tab already shows the curl one-liner — no change required to the command itself, but consider adding a second line of copy: "isolated install via uv tool → pipx → venv fallback; CLI available at ~/.local/bin/praisonai".

5. docs/developers/scripts.mdx

  • Refresh the install.sh description from "One-liner installer for macOS/Linux" to something like "Frictionless, environment-isolated one-liner installer (uv tool → pipx → venv fallback)".

6. docs/features/onboard.mdx

  • The existing examples (--no-onboard / PRAISONAI_NO_ONBOARD=1) remain correct. No change required, but verify the page still reads correctly alongside the new completion-install prompt — both prompts now appear in sequence.

B. CREATE (optional, recommended)

A small new page or callout that helps users pick between backends, per AGENTS.md §6.1 ("If multiple options in one page, people might be confused on what to choose, so create the mermaid diagram to choose what option at what instance.").

Suggested page: docs/install/isolation-backends.mdx (placed under the existing Install group, NOT docs/concepts/):

  • Hero mermaid: a "choose-your-backend" decision tree (Have uv? → uv / Have pipx? → pipx / Neither? → venv fallback).
  • Side-by-side comparison table (uv tool vs. pipx vs. venv vs. pip install into active env): isolation, persistence, speed, who manages PATH, when to pick each.
  • Examples for each, including the --backend flag and PRAISONAI_BACKEND env var.
  • Cross-link from installer.mdx and quickstart.mdx.

If a separate page is overkill, fold the same decision diagram + comparison table into a new ## Choosing a backend section inside installer.mdx.

Source of truth (SDK files to read before writing)

Per AGENTS.md §1.2 "SDK-First Documentation Cycle" — read these first, do not paraphrase from this issue:

  • src/praisonai/scripts/install.sh — the actual installer. Key functions to read:
    • detect_backend (preference order + PRAISONAI_BACKEND parsing)
    • build_package_spec (default praisonai[all], honours PRAISONAI_EXTRAS and PRAISONAI_VERSION)
    • install_with_uv, install_with_pipx, create_venv, create_shim
    • detect_shell_rc, ensure_path_dir (the # >>> PraisonAI PATH >>> block)
    • maybe_install_completions (prompt logic, fish vs. bash/zsh, idempotency grep)
    • resolve_praisonai_cmd, verify_installation
    • print_help and parse_args — canonical list of CLI flags
    • The main() case "$backend" block — definitive runtime flow
  • src/praisonai/praisonai/cli/commands/completion.py (or equivalent) — the praisonai completion <shell> subcommand the installer shells out to.
  • Diff for full context: https://github.com/MervinPraison/PraisonAI/pull/2176/files
  • Original spec: issue MervinPraison/PraisonAI#2173

The PR adds 391 lines / removes 70 in a single file. The diff is the ground truth; this issue is a planning aid.

Authoritative reference values (extracted from the diff for quick check)

These are extracted from the merged PR and should be cross-checked against the SDK file when writing:

Backend preference order (auto): uv tool → pipx → venv fallback.

New defaults:

  • INSTALL_DIR → $HOME/.praisonai
  • BACKEND → auto
  • NO_MODIFY_PATH → 0
  • SHIM_DIR → $HOME/.local/bin
  • Default package spec for curl-pipe-bash → praisonai[all] (not bare praisonai)
  • MIN_PYTHON_VERSION → 3.10 (unchanged)

All CLI flags after the PR:
--version VERSION, --extras EXTRAS, --backend BACKEND, --install-dir DIR, --no-modify-path, --no-venv, --no-onboard, --python PATH, --dry-run, --no-prompt, -h, --help.

All env vars after the PR:
PRAISONAI_VERSION, PRAISONAI_EXTRAS, PRAISONAI_NO_PROMPT, PRAISONAI_DRY_RUN, PRAISONAI_PYTHON, PRAISONAI_SKIP_VENV, PRAISONAI_NO_ONBOARD, PRAISONAI_INSTALL_DIR, PRAISONAI_BACKEND, PRAISONAI_NO_MODIFY_PATH.

Valid --backend values: uv, pipx, venv, system, auto. (system is what --no-venv / PRAISONAI_SKIP_VENV=1 resolve to.)

Shell rc PATH block markers:

# >>> PraisonAI PATH >>>
export PATH="$bin_dir:$PATH"   # or `set -gx PATH $bin_dir $PATH` for fish
# <<< PraisonAI PATH <<<

Completion targets:

  • bash → appends to ~/.bashrc (skip if _praisonai_completion or #compdef praisonai already present)
  • zsh → appends to ~/.zshrc (same idempotency check)
  • fish → writes ~/.config/fish/completions/praisonai.fish (overwrites)

Completion prompt is auto-skipped when any of: --no-onboard, --no-prompt, --dry-run, or /dev/tty is unavailable.

Folder placement rules (AGENTS.md §1.8)

  • All updated / new pages MUST live under docs/install/, docs/features/, docs/guides/, or similar — NEVER docs/concepts/ (docs/concepts/ is human-approved only).
  • If a new "Choosing a backend" page is created, place it at docs/install/isolation-backends.mdx and register it under the existing Install group in docs.json (not under "Concepts").
  • After modifying docs.json, verify it is valid JSON.

Style / quality checklist (AGENTS.md §6, §9)

For the agent implementing this:

  • Read src/praisonai/scripts/install.sh end-to-end before writing any content.
  • Every page starts with one sentence + a hero mermaid diagram (standard colour scheme, white text).
  • Use <Steps>, <AccordionGroup>, <CardGroup>, <Tabs>, <Note>, <Warning> Mintlify components.
  • Code examples are copy-paste-runnable (full curl commands, real flag values — no <your-…> placeholders).
  • Active voice, no forbidden phrases ("In this section…", "As you can see…", "Please note that…").
  • All config options documented exactly as they appear in the SDK (names, types, defaults).
  • Update docs.json if a new page is added; keep all entries under Install / Features (never Concepts).
  • Verify docs.json is valid JSON after edits.
  • Agent-centric perspective: lead with what a non-developer types, not how the installer is implemented internally.
  • Include a user-interaction flow diagram (one of the mermaid diagrams should be a sequenceDiagram of User → curl → Installer → Backend → Shell rc → CLI).

Acceptance criteria

  • docs/install/installer.mdx documents all three backends, all new flags (--backend, --install-dir, --no-modify-path), all new env vars (PRAISONAI_BACKEND, PRAISONAI_INSTALL_DIR, PRAISONAI_NO_MODIFY_PATH), the ~/.local/bin/praisonai shim, and the praisonai completion integration.
  • docs/install/quickstart.mdx shows uvx and pipx install praisonai as first-class one-liners alongside the curl installer.
  • docs/installation.mdx, docs/index.mdx, docs/developers/scripts.mdx reference the new isolation behaviour where they currently describe a venv-only install.
  • A "Choosing a backend" diagram + comparison table exists (either as a standalone page under docs/install/ or as a section in installer.mdx).
  • No docs/concepts/ files were touched.
  • docs.json is valid JSON after edits; any new page is registered under Install.
  • Every example runs as-shown against the installer in src/praisonai/scripts/install.sh at PR #2176's merge commit (b1776e1942365d32764b42c9efa8327d36a7721d).

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    claudeTrigger Claude Code analysisdocumentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions