Quick Start

Launch PySH and use the stable v1 command, Python, diagnostics, and script surfaces.

Launch PySH

Launch and inspect

$ pysh --version

pysh 1.0.0

$ pysh --credits

PySH Project Authors

$ pysh

Type 'exit' or press Ctrl+D to quit.

Interactive shell commands

External commands, PySH builtins, pipelines, redirections, chaining, heredocs, history, completion, and foreground job control are available through the documented PySH shell contract.

Shell workflow

$ pwd

$ ls -la

$ printf "one two " | grep two

two

$ cd /tmp && pwd

/tmp

Inline Python — py

py <code> executes one-line Python in a persistent runtime context for the current shell session. It uses exec semantics, so print expression results explicitly.

Persistent inline Python

$ py x = 10

$ py print(x * 5)

$ py from pathlib import Path; print(Path(".").resolve())

Multi-line Python blocks

Start a block with py { and close it with a line containing only }. The block shares state with one-line py commands.

Python block

$ py {

import os

print(len(os.environ.get("PATH", "").split(":")))

}

Interactive Python mode — #py

Type #py to enter the Python Command Execution Layer. Use #exit or Ctrl+D to return to the normal PySH prompt.

Python command mode

$ #py

PySH Python Command Execution Layer | GPL-2.0-only

Python <current runtime>

Type #help for commands. Ctrl+D or #exit to return to PySH.

$ x = [1, 2, 3]

$ sum(x)

$ #exit

✓#help — show Python-mode directives
✓#open <file> — load Python source into the editing buffer
✓#save [file] — save the current source buffer
✓#show [file] — show the buffer or a file
✓#run — execute the source buffer
✓#clear / #reset — clear buffer state or buffer plus runtime state

PySH-native script mode

Run a .pysh script

$ pysh script.pysh arg1 arg2

Warning: PySH-native scripts follow the PySH language contract. PySH is not POSIX /bin/sh and does not silently delegate unsupported syntax to another shell.

Diagnostics and recovery

Operational diagnostics

$ pysh --debug -c "echo hi"

$ pysh --diagnostics-json -c "echo hi"

$ pysh --audit-log ~/.local/state/pysh-audit.jsonl -c "echo hi"

$ pysh --no-rc -c "echo recovery-ok"

Debug and structured diagnostics are redacted and emitted separately from normal command stdout. The optional audit log is private, opt-in, and does not change command execution. --no-rc starts from built-in defaults without reading user configuration or plugins.

Exit PySH

Type exit or quit, or press Ctrl+D at the normal PySH prompt.