PySH Documentation

Stable 1.0.0

Stable documentation for PySH 1.0.0: installation, interactive shell behavior, .pysh scripts, the Python Execution Layer, Plugin API 1.0, configuration, platform support, diagnostics, and release verification.

Install PySH 1.0.0

# CPython 3.13 or newer

$ python3.13 -m pip install --upgrade pip

$ python3.13 -m pip install pysh-shell

$ pysh --version

pysh 1.0.0

$ python -m pysh --version

pysh 1.0.0

$ pysh --credits

Getting Started Installation Configuration Plugin API 1.0

Getting Started

Overview

What PySH is, its v1 contract, and when to use it.

Installation

Install from PyPI or GitHub Release packages on supported Unix families.

Quick Start

Interactive shell, command mode, inline Python, and .pysh scripts.

Supported Platforms

Tier 1 and Tier 2 runtime-family support for PySH v1.

Python Execution Layer

Overview

Persistent Python execution inside the current PySH process.

Interactive #py

Enter and leave the persistent interactive Python layer.

Inline py

Execute one-line Python with exec semantics.

Block Mode

Execute multi-line Python blocks with py { ... }.

Configuration

Configuration Model

TOML, deterministic drop-ins, legacy rc compatibility, and ~/.pyshrc.py.

Safe Startup

Use --no-rc for deterministic recovery and conformance runs.

Prompt & History

Configure prompt layout, history, profiles, themes, and colors.

Themes

Built-in profiles/themes and declarative visual customization.

Plugin API 1.0

Plugin Overview

Trusted local plugins and the stable Plugin API 1.0 contract.

Plugin Class

Define metadata, api_version, registration, and commands.

Enablement

Explicit user and project-local plugin opt-in.

Isolation Boundary

Understand trusted plugins versus isolated subprocess plugins.

Shell & Script Contract

Interactive Shell

Commands, pipelines, redirections, chaining, history, completion, and job control.

.pysh Script Mode

Run PySH scripts explicitly without pretending to be /bin/sh.

Compatibility

PySH is Python-first and does not claim Bash/Zsh/Fish/POSIX compatibility.

Troubleshooting

Recovery startup, interpreter checks, plugin diagnostics, and support paths.

Release & Supply Chain

PyPI

Install the published pysh-shell distribution.

Native Packages

Install .deb, .rpm, and reference FreeBSD .pkg assets.

Verification

Verify checksums, provenance, SPDX SBOMs, and release artifacts.

GitHub Release

Download the latest published PySH release assets.

Related Projects

PySH Academy

Learning tracks for Python automation and PySH workflows.

ECLI Roadmap

Separate engineering-workspace project planned to integrate with PySH.

IDE Roadmap

Planned editor and terminal integration work.

Community

GitHub and Telegram project channels.