pehloo-shell 0.1.0__tar.gz

pehloo_shell-0.1.0/.env.example

@@ -0,0 +1,8 @@
+# Cline-pass judge model (OpenAI-compatible API) that grades semantic correctness.
+CLINE_API_KEY=your_api_key_here
+CLINE_BASE_URL=https://api.cline.bot/api/v1
+CLINE_JUDGE_MODEL=cline-pass/deepseek-v4-flash
+
+# The evaluated local ggufs are served by llama-server on :8080. Inspect's
+# "llamacpp" provider still expects an API key; llama-server ignores it.
+LLAMACPP_API_KEY=unused

pehloo_shell-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,60 @@
+name: publish
+
+# Publishes to PyPI with trusted publishing (OIDC) — no API token is stored
+# anywhere. The PyPI publisher form must match this repository row for row:
+#
+#   PyPI Project Name: pehloo-shell
+#   Owner:             ribhu97
+#   Repository name:   pehloo-shell
+#   Workflow name:     publish.yml
+#   Environment name:  pypi
+#
+# If you leave "Environment name" blank on PyPI, delete `environment: pypi`
+# below as well: the OIDC token carries the environment, and a mismatch is
+# rejected. A release publishes whatever version `pyproject.toml` declares, so
+# bump it first, then tag `v<version>`.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10
+        with:
+          python-version: "3.13"
+      - name: Build
+        run: uv build
+      - name: Check the artifact metadata before anything is uploaded
+        run: uv publish --dry-run dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Must match the Environment name configured on PyPI (see the header).
+    environment: pypi
+    permissions:
+      id-token: write # the OIDC token that trusted publishing exchanges for upload rights
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@v10
+      - name: Publish
+        # `--check-url` skips files PyPI already has, so re-running a release is
+        # a no-op instead of an error.
+        run: uv publish --trusted-publishing always --check-url https://pypi.org/simple/ dist/*

pehloo_shell-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+__pycache__/
+*.py[cod]
+.env
+inspect-logs/
+logs/
+dist/
+build/
+*.egg-info/
+.DS_Store
+
+# Private for now — kept out of the public repo and the PyPI sdist.
+benchmark/
+
+# Editor/agent configuration.
+.serena/
+.claude/
+.mcp.json
+*.log
+.ruff_cache/

pehloo_shell-0.1.0/AGENTS.md

@@ -0,0 +1,148 @@
+# AGENTS.md
+
+Guidance for humans and AI agents working in this repository.
+
+## Project in one line
+
+`pehloo-shell` (CLI: `pls`) turns a natural-language request into a shell command
+via an OpenAI-compatible model server (local llama.cpp by default, or Cerebras,
+Groq, OpenRouter). It prints the command, then asks whether to run, reject or
+change it — nothing executes without an explicit `y`. From Pehloo
+(<https://pehloo.xyz>).
+
+## Layout
+
+- `src/pehloo_shell/cli.py` — the `pls` CLI: settings resolution, the model call,
+  and the run/reject/change confirmation loop.
+- `src/pehloo_shell/providers.py` — the backend registry (local + hosted), URL
+  derivation, and `/models` discovery. Add a backend here and nowhere else.
+- `src/pehloo_shell/onboarding.py` — the first-run setup wizard and the config
+  file writer. Also reachable with `pls --setup`.
+- `install.sh` — the `curl … | sh` installer (uv → pipx → pip, user-level only).
+- `tests/test_cli.py`, `tests/test_providers.py`, `tests/test_onboarding.py` —
+  unit tests (mock the HTTP layer and `input`).
+- `benchmark/` is private and gitignored (kept out of the public repo and the
+  PyPI sdist "for now"); its tooling and run instructions live in
+  `benchmark/AGENTS.md`. The same applies to `.serena/`, `.claude/` and
+  `.mcp.json`.
+
+## Environment
+
+- The project uses a `uv`-managed venv (`.venv`):
+
+  ```bash
+  uv venv .venv
+  uv sync            # installs the `pls` CLI and its one dependency
+  ```
+
+  `uv.lock` is committed; keep it in sync when you touch `pyproject.toml`.
+  Benchmark tooling (`inspect-ai`, `openai`, `matplotlib`) is not part of the
+  package — install it as a local overlay when you work in `benchmark/`:
+  `uv pip install --python .venv/bin/python inspect-ai openai matplotlib`
+  (`uv sync` removes the overlay again).
+
+- `.env` holds secrets and local defaults (cline-pass judge, local llama-server).
+  Never commit a real API key — `.env` is gitignored; put placeholders in
+  `.env.example` instead.
+
+- End users install with `install.sh` (`sh install.sh` from a checkout, or
+  `curl -fsSL <url> | sh`): uv → pipx → pip, user-level only, no sudo. It
+  installs the `pehloo-shell` package from PyPI unless `--source` /
+  `$PEHLOO_SHELL_SOURCE` says otherwise.
+
+## Branding & voice
+
+Public surfaces match <https://pehloo.xyz>:
+
+- The ANSI-shadow `PEHLOO` wordmark (top of `README.md`, header of
+  `install.sh`) — the exact 6 lines are on the site's landing page.
+- Status tags look like `[ PLS_INSTALL ]` and `[ COMING_SOON ]` — square
+  brackets, words_joined_by_underscores, sometimes boxed with `╔═╗`.
+- Progress and pointer lines start with `▸` (the wizard, the installer).
+- Terse terminal voice: "Natural language in, shell command out." — no
+  marketing, no filler. Fonts on the site are Share Tech Mono / Space Mono /
+  VT323; accent colour is brand-amber `#d4a017` on cream `#f5f2eb`.
+- `pls` itself prints the command then `[y] run  [n] reject  [c] change >`.
+
+## How `pls` behaves (keep these contracts)
+
+- **Nothing executes without an explicit `y`** at the `[y] run  [n] reject
+  [c] change` prompt. Enter and `n` reject; unknown keys ask again.
+- **Non-interactive runs never execute**: with stdin/stdout not a terminal,
+  `pls` prints the command and stops, so pipes and scripts stay safe.
+- `y` propagates the command's exit status as `pls`'s own; Ctrl-C/Ctrl-D at a
+  prompt is 130; a missing request is 2.
+- `c` sends the revision as a follow-up turn (`previous_command` + `change` in
+  `generate_command`), so revisions keep the original request as context.
+- The setup wizard runs only when there is no config file and the session is
+  interactive, or when `--setup` is passed.
+- New backends go in `providers.py`; nothing else should know provider URLs or
+  API-key environment variables.
+
+## Releasing (PyPI)
+
+`install.sh` defaults to the `pehloo-shell` package on PyPI, so publishing is what
+makes `pipx install pehloo-shell` work for everyone else.
+
+Releases go out from `.github/workflows/publish.yml` using trusted publishing —
+no API token is stored in the repo or in GitHub secrets. PyPI's publisher form
+("pending publisher" for a project that does not exist yet) must match that file
+exactly:
+
+| PyPI field | Value |
+| --- | --- |
+| PyPI Project Name | `pehloo-shell` |
+| Owner | `ribhu97` |
+| Repository name | `pehloo-shell` |
+| Workflow name | `publish.yml` |
+| Environment name | `pypi` — the workflow sets `environment: pypi`; leaving this blank on PyPI means deleting that line too |
+
+Then: bump `version` in `pyproject.toml`, commit, tag `v<version>`, publish a
+GitHub release. The workflow builds the artifacts, validates their metadata with
+`uv publish --dry-run`, and uploads them with OIDC. `workflow_dispatch` re-runs it
+on demand; `--check-url` makes that a no-op for files PyPI already has.
+
+Publishing by hand, with a token, still works:
+
+```bash
+uv build                                    # dist/*.whl + dist/*.tar.gz
+uv publish --dry-run dist/*                 # validates the metadata, stops at credentials
+
+# optional rehearsal on TestPyPI, then install from there
+uv publish --publish-url https://test.pypi.org/legacy/ --token "$TESTPYPI_TOKEN" dist/*
+pipx install --index-url https://test.pypi.org/simple/ \
+    --pip-args="--extra-index-url https://pypi.org/simple/" pehloo-shell
+
+uv publish --token "$PYPI_TOKEN" dist/*     # the real thing
+```
+
+- Credentials for the manual path come from `UV_PUBLISH_TOKEN` / `--token`, or a
+  token from <https://pypi.org/manage/account/token/>; never put one in the repo.
+- Bump `version` in `pyproject.toml` for every upload — PyPI rejects a version it
+  already has, so a fix means a new version, not a re-upload.
+- The sdist ships the package, tests and docs only; `.env`, `logs/`,
+  `benchmark/`, `.serena/`, `.claude/` and `.mcp.json` are excluded (see
+  `[tool.hatch.build.targets.sdist]` in `pyproject.toml`). After touching
+  packaging, re-check with `tar tzf dist/*.tar.gz` — the sdist must never contain
+  `.env`.
+- Published installs are copies: `pipx install pehloo-shell` and
+  `uv tool install pehloo-shell` need `--force` (or `pipx upgrade` /
+  `uv tool upgrade`) to pick up a release.
+
+## Working agreements
+
+1. **Keep code human readable.**
+   - No unnecessary abstractions. Plain functions and simple data flow beat clever
+     design patterns.
+   - No god-functions. If a function does more than one clearly named thing, split it.
+   - Inline comments and docstrings explain *why*, not just *what*. A stranger should
+     be able to read the code top-to-bottom without spelunking.
+
+## Before committing
+
+- Unit tests should pass: `uv run python -m unittest discover tests`
+- CLI still runs: `uv run pls "list files by size"` (interactive), and
+  `echo "list files by size" | uv run pls` must print the command and run nothing.
+- Installer still parses and installs: `sh -n install.sh`, then
+  `uv tool install --force .` (or `sh install.sh`).
+- `.env` must not contain real secrets (only placeholders).

pehloo_shell-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ribhu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pehloo_shell-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.5
+Name: pehloo-shell
+Version: 0.1.0
+Summary: Natural language in, shell command out — review it, then press y to run. A Pehloo tool.
+Project-URL: Homepage, https://pehloo.xyz
+Author: Ribhu
+License: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Requires-Dist: python-dotenv>=1
+Description-Content-Type: text/markdown
+
+```
+██████╗ ███████╗██╗  ██╗██╗      ██████╗  ██████╗
+██╔══██╗██╔════╝██║  ██║██║     ██╔═══██╗██╔═══██╗
+██████╔╝█████╗  ███████║██║     ██║   ██║██║   ██║
+██╔═══╝ ██╔══╝  ██╔══██║██║     ██║   ██║██║   ██║
+██║     ███████╗██║  ██║███████╗╚██████╔╝╚██████╔╝
+╚═╝     ╚══════╝╚═╝  ╚═╝╚══════╝ ╚═════╝  ╚═════╝
+```
+
+# pls
+
+**Natural language in, shell command out. Review it, then press `y`.**
+
+`pls` is the Pehloo shell assistant — from [Pehloo](https://pehloo.xyz), AI
+tools for builders who ship. It asks an OpenAI-compatible model to turn your
+request into one shell command, shows it to you, and waits:
+
+```console
+$ pls "list the 10 largest directories in the current folder"
+du -h --max-depth=1 | sort -hr | head -n 10
+[y] run  [n] reject  [c] change >
+```
+
+- `y` runs the command in your shell; `pls` exits with its status.
+- `n` or Enter rejects it — nothing runs.
+- `c` asks the model to change it (e.g. type `sort by size instead`) and shows
+  the revision, with the previous command as context.
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ribhu97/pehloo-shell/main/install.sh | sh
+sh install.sh                                     # from a checkout
+```
+
+The installer works at user level — no sudo, no system Python — using uv, pipx
+or pip, whichever you have, and prints the installed `pls` path plus the
+`export PATH=…` line if you need one. It installs the `pehloo-shell` package
+from PyPI, falling back to this repository while the package is unpublished.
+Point it elsewhere with `--source` / `$PEHLOO_SHELL_SOURCE`:
+
+```bash
+sh install.sh --source "git+https://github.com/ribhu97/pehloo-shell"
+```
+
+Already have a Python tool runner? Skip the script:
+
+```bash
+uv tool install pehloo-shell     # or: pipx install pehloo-shell
+```
+
+For development see [AGENTS.md](AGENTS.md) (`uv sync`, then `.venv/bin/pls`).
+Note that `pipx install .` and `uv tool install .` copy the code — rerun them
+after changing the CLI.
+
+## Setup
+
+The first run with no config asks which backend to use:
+
+```console
+╔══════════════════════════════╗
+║   PLS_SETUP: MODEL_BACKEND   ║
+╚══════════════════════════════╝
+▸ pehloo-shell · a Pehloo tool (pehloo.xyz)
+▸ your answers are saved to ~/.pehloo/shell-config.json (re-run any time with `pls --setup`)
+
+Use a local model server? [Y/n]: y
+
+Local server: llama.cpp, Ollama, LM Studio or vLLM — any OpenAI-compatible server.
+Server URL [http://127.0.0.1:8080/v1]:
+API key (leave blank if the server has none):
+  1. LFM2.5-1.2B-Instruct-Q8_0.gguf  (default)
+  2. MiniCPM5-2B
+Model number or name [1]:
+```
+
+- **Local** (`y`): any OpenAI-compatible server — llama.cpp, Ollama, LM Studio,
+  vLLM. `pls` reads its `/v1/models` list so you can pick a model instead of
+  guessing a name.
+- **Hosted** (`n`): Cerebras, Groq or OpenRouter. The wizard tells you where to
+  create a key and detects the provider's models with it. A key already in your
+  environment is used without being copied into the config file.
+
+Re-run setup any time with `pls --setup`, or edit `~/.pehloo/shell-config.json`
+by hand.
+
+## Non-interactive
+
+```bash
+echo "show files changed today" | pls    # prints the command, runs nothing
+pls --markdown "show my current directory"
+```
+
+When stdin is not a terminal — pipes, scripts, CI — `pls` prints the command and
+stops. Nothing executes without an explicit `y` at a terminal.
+
+## Environment variables
+
+Handy for CI, or to keep the API key out of the config file. They override the
+config file; command-line flags override both.
+
+| Variable | Meaning |
+| --- | --- |
+| `PEHLOO_SHELL_CONFIG` | where the config file lives (default `~/.pehloo/shell-config.json`) |
+| `PEHLOO_SHELL_PROVIDER` | `llama.cpp`, `cerebras`, `groq` or `openrouter` |
+| `PEHLOO_SHELL_API_KEY` | API key for any provider |
+| `CEREBRAS_API_KEY`, `GROQ_API_KEY`, `OPENROUTER_API_KEY` | provider-specific keys |
+| `LFM_SHELL_URL` | chat-completions URL of any OpenAI-compatible server |
+| `LFM_SHELL_MODEL` | model name to send |
+
+Read the command before you press `y`: model output can be destructive.

pehloo_shell-0.1.0/README.md

@@ -0,0 +1,111 @@
+```
+██████╗ ███████╗██╗  ██╗██╗      ██████╗  ██████╗
+██╔══██╗██╔════╝██║  ██║██║     ██╔═══██╗██╔═══██╗
+██████╔╝█████╗  ███████║██║     ██║   ██║██║   ██║
+██╔═══╝ ██╔══╝  ██╔══██║██║     ██║   ██║██║   ██║
+██║     ███████╗██║  ██║███████╗╚██████╔╝╚██████╔╝
+╚═╝     ╚══════╝╚═╝  ╚═╝╚══════╝ ╚═════╝  ╚═════╝
+```
+
+# pls
+
+**Natural language in, shell command out. Review it, then press `y`.**
+
+`pls` is the Pehloo shell assistant — from [Pehloo](https://pehloo.xyz), AI
+tools for builders who ship. It asks an OpenAI-compatible model to turn your
+request into one shell command, shows it to you, and waits:
+
+```console
+$ pls "list the 10 largest directories in the current folder"
+du -h --max-depth=1 | sort -hr | head -n 10
+[y] run  [n] reject  [c] change >
+```
+
+- `y` runs the command in your shell; `pls` exits with its status.
+- `n` or Enter rejects it — nothing runs.
+- `c` asks the model to change it (e.g. type `sort by size instead`) and shows
+  the revision, with the previous command as context.
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ribhu97/pehloo-shell/main/install.sh | sh
+sh install.sh                                     # from a checkout
+```
+
+The installer works at user level — no sudo, no system Python — using uv, pipx
+or pip, whichever you have, and prints the installed `pls` path plus the
+`export PATH=…` line if you need one. It installs the `pehloo-shell` package
+from PyPI, falling back to this repository while the package is unpublished.
+Point it elsewhere with `--source` / `$PEHLOO_SHELL_SOURCE`:
+
+```bash
+sh install.sh --source "git+https://github.com/ribhu97/pehloo-shell"
+```
+
+Already have a Python tool runner? Skip the script:
+
+```bash
+uv tool install pehloo-shell     # or: pipx install pehloo-shell
+```
+
+For development see [AGENTS.md](AGENTS.md) (`uv sync`, then `.venv/bin/pls`).
+Note that `pipx install .` and `uv tool install .` copy the code — rerun them
+after changing the CLI.
+
+## Setup
+
+The first run with no config asks which backend to use:
+
+```console
+╔══════════════════════════════╗
+║   PLS_SETUP: MODEL_BACKEND   ║
+╚══════════════════════════════╝
+▸ pehloo-shell · a Pehloo tool (pehloo.xyz)
+▸ your answers are saved to ~/.pehloo/shell-config.json (re-run any time with `pls --setup`)
+
+Use a local model server? [Y/n]: y
+
+Local server: llama.cpp, Ollama, LM Studio or vLLM — any OpenAI-compatible server.
+Server URL [http://127.0.0.1:8080/v1]:
+API key (leave blank if the server has none):
+  1. LFM2.5-1.2B-Instruct-Q8_0.gguf  (default)
+  2. MiniCPM5-2B
+Model number or name [1]:
+```
+
+- **Local** (`y`): any OpenAI-compatible server — llama.cpp, Ollama, LM Studio,
+  vLLM. `pls` reads its `/v1/models` list so you can pick a model instead of
+  guessing a name.
+- **Hosted** (`n`): Cerebras, Groq or OpenRouter. The wizard tells you where to
+  create a key and detects the provider's models with it. A key already in your
+  environment is used without being copied into the config file.
+
+Re-run setup any time with `pls --setup`, or edit `~/.pehloo/shell-config.json`
+by hand.
+
+## Non-interactive
+
+```bash
+echo "show files changed today" | pls    # prints the command, runs nothing
+pls --markdown "show my current directory"
+```
+
+When stdin is not a terminal — pipes, scripts, CI — `pls` prints the command and
+stops. Nothing executes without an explicit `y` at a terminal.
+
+## Environment variables
+
+Handy for CI, or to keep the API key out of the config file. They override the
+config file; command-line flags override both.
+
+| Variable | Meaning |
+| --- | --- |
+| `PEHLOO_SHELL_CONFIG` | where the config file lives (default `~/.pehloo/shell-config.json`) |
+| `PEHLOO_SHELL_PROVIDER` | `llama.cpp`, `cerebras`, `groq` or `openrouter` |
+| `PEHLOO_SHELL_API_KEY` | API key for any provider |
+| `CEREBRAS_API_KEY`, `GROQ_API_KEY`, `OPENROUTER_API_KEY` | provider-specific keys |
+| `LFM_SHELL_URL` | chat-completions URL of any OpenAI-compatible server |
+| `LFM_SHELL_MODEL` | model name to send |
+
+Read the command before you press `y`: model output can be destructive.

pehloo_shell-0.1.0/install.sh

@@ -0,0 +1,175 @@
+#!/bin/sh
+# Install the `pls` CLI from pehloo-shell.
+#
+#   curl -fsSL https://example.com/install.sh | sh
+#
+# Options:
+#   --source SPEC   what to install (default: the `pehloo-shell` package)
+#                   examples: --source .
+#                             --source "git+https://github.com/you/pehloo-shell"
+#
+# Installs into your user account only: no sudo, no system Python, no files
+# outside your home directory. Run it again to upgrade.
+set -eu
+
+SOURCE="${PEHLOO_SHELL_SOURCE:-pehloo-shell}"
+# Fallback used when the PyPI package is not available (see the install step).
+REPO_SOURCE="git+https://github.com/ribhu97/pehloo-shell"
+MIN_PYTHON="3.10"
+
+usage() {
+    cat <<'EOF'
+Install the pls CLI.
+
+Usage: install.sh [--source SPEC]
+
+  --source SPEC   pip requirement to install (default: the pehloo-shell package
+                  on PyPI, falling back to the GitHub repository when the
+                  package is not published). Also read from $PEHLOO_SHELL_SOURCE.
+  --help          show this message.
+
+Installing from a checkout of this repository installs that checkout.
+EOF
+}
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --source|-s)
+            [ $# -ge 2 ] || { echo "install.sh: --source needs a value" >&2; exit 2; }
+            SOURCE="$2"
+            shift 2
+            ;;
+        --help|-h)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "install.sh: unknown option '$1'" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+# --- Banner -----------------------------------------------------------------
+
+cat <<'BANNER'
+
+██████╗ ███████╗██╗  ██╗██╗      ██████╗  ██████╗
+██╔══██╗██╔════╝██║  ██║██║     ██╔═══██╗██╔═══██╗
+██████╔╝█████╗  ███████║██║     ██║   ██║██║   ██║
+██╔═══╝ ██╔══╝  ██╔══██║██║     ██║   ██║██║   ██║
+██║     ███████╗██║  ██║███████╗╚██████╔╝╚██████╔╝
+╚═╝     ╚══════╝╚═╝  ╚═╝╚══════╝ ╚═════╝  ╚═════╝
+[ PLS_INSTALL ]  pehloo-shell · a Pehloo tool (pehloo.xyz)
+
+BANNER
+
+# Running inside the repository? Install that, so `sh install.sh` in a checkout
+# does the obvious thing.
+if [ "$SOURCE" = "pehloo-shell" ] && [ -f pyproject.toml ] && [ -f src/pehloo_shell/cli.py ]; then
+    SOURCE="."
+    echo "▸ installing from this checkout"
+fi
+
+# --- Python -----------------------------------------------------------------
+
+PY=""
+for candidate in python3 python; do
+    if command -v "$candidate" >/dev/null 2>&1; then
+        PY="$(command -v "$candidate")"
+        break
+    fi
+done
+
+if [ -z "$PY" ]; then
+    echo "install.sh: python3 not found." >&2
+    echo "  macOS:  brew install python" >&2
+    echo "  Debian: sudo apt install python3 python3-pip" >&2
+    exit 1
+fi
+
+if ! "$PY" -c "import sys; raise SystemExit(0 if sys.version_info >= tuple(int(p) for p in '$MIN_PYTHON'.split('.')) else 1)"; then
+    echo "install.sh: python $MIN_PYTHON or newer is required, found $("$PY" -V 2>&1)." >&2
+    exit 1
+fi
+
+# --- Install ----------------------------------------------------------------
+
+installer=""
+
+# Install one pip requirement with whichever tool this machine has.
+try_install() {
+    spec="$1"
+    if [ -z "$installer" ]; then
+        if command -v uv >/dev/null 2>&1; then
+            installer="uv"
+        elif command -v pipx >/dev/null 2>&1; then
+            installer="pipx"
+        else
+            installer="pip"
+        fi
+    fi
+    case "$installer" in
+        uv)   echo "▸ uv tool install $spec"; uv tool install --force "$spec" ;;
+        pipx) echo "▸ pipx install $spec"; pipx install --force "$spec" ;;
+        *)    echo "▸ $PY -m pip install --user --upgrade $spec"; "$PY" -m pip install --user --upgrade "$spec" ;;
+    esac
+}
+
+if ! try_install "$SOURCE"; then
+    if [ "$SOURCE" = "pehloo-shell" ]; then
+        # Nothing published on PyPI yet (or PyPI is down): install straight from
+        # the repository so the advertised `curl … | sh` always works.
+        echo "▸ pehloo-shell is not on PyPI yet — installing from $REPO_SOURCE"
+        if ! try_install "$REPO_SOURCE"; then
+            echo "install.sh: could not install $REPO_SOURCE." >&2
+            exit 1
+        fi
+    else
+        echo "install.sh: could not install $SOURCE." >&2
+        if [ "$installer" = "pip" ]; then
+            echo "  This is often an externally-managed environment (PEP 668). Install uv or pipx and rerun:" >&2
+            echo "    curl -LsSf https://astral.sh/uv/install.sh | sh" >&2
+        fi
+        exit 1
+    fi
+fi
+
+# --- Report -----------------------------------------------------------------
+
+case "$installer" in
+    uv)   bin_dir="${UV_TOOL_BIN_DIR:-$HOME/.local/bin}" ;;
+    pipx) bin_dir="${PIPX_BIN_DIR:-$HOME/.local/bin}" ;;
+    *)    bin_dir="$("$PY" -c 'import sysconfig; print(sysconfig.get_path("scripts", scheme="posix_user"))')" ;;
+esac
+installed="$bin_dir/pls"
+
+if [ ! -x "$installed" ]; then
+    echo "install.sh: $installer finished but $installed is missing." >&2
+    echo "  Look for the tool in $bin_dir and report this at the project's issue tracker." >&2
+    exit 1
+fi
+echo "▸ installed: $installed"
+
+if ! command -v pls >/dev/null 2>&1; then
+    echo "▸ $bin_dir is not on your PATH. Add it:"
+    echo "    export PATH=\"$bin_dir:\$PATH\""
+elif [ "$(command -v pls)" != "$installed" ]; then
+    # A different pls earlier on PATH would silently win over this install.
+    echo "▸ note: the 'pls' on your PATH is $(command -v pls), not this one."
+fi
+
+case "$installer" in
+    uv)   echo "▸ upgrade:   uv tool upgrade pehloo-shell" ;;
+    pipx) echo "▸ upgrade:   pipx upgrade pehloo-shell" ;;
+    *)    echo "▸ upgrade:   $PY -m pip install --user --upgrade pehloo-shell" ;;
+esac
+
+cat <<'EOF'
+
+▸ next:    pls "list files by size"   — the first run sets up your model backend
+▸ local:   llama.cpp, Ollama, LM Studio or vLLM (any OpenAI-compatible server)
+▸ hosted:  Cerebras · Groq · OpenRouter
+▸ config:  ~/.pehloo/shell-config.json · re-run setup with `pls --setup`
+EOF