Step-by-step tutorial¶

Learn the implemented shell-next features through small operations, then combine them into a working report job. Each chapter has one to three examples, ordered from simple to more involved, and a complete standalone Python file in examples/. Assertions explain observable results; no external account or project is needed except when you explicitly choose the sudo chapter.

Setup and backend selection¶

Install Python 3.14+ and shell-next 0.1.3 or newer, then use a repository checkout to access the example files (they are not installed as package entry points):

python -m pip install shell-next

Run from the checkout root. Pick the backend supported by your host:

Host	Shell prerequisite	Example command
Linux, including the RHEL 8 reference platform	Bash	`python examples/01-commands.py bash`
Windows	PowerShell 7 (`pwsh`)	`python examples/01-commands.py powershell`
Windows	cmd (provided by Windows)	`python examples/01-commands.py cmd`

Repeat the selected backend argument for each native chapter. Without it, examples default to cmd on Windows and Bash on Linux. The mock chapter needs no backend argument. Sudo requires an explicit backend and mode. In a checkout under development use python -m pip install -e ".[dev,docs]" in your environment first.

Every file has imports, an async entry point, assertions, and an asyncio.run() guard. In an existing async application await main(...) instead of nesting asyncio.run(). startup_timeout=30 gives cold PowerShell startup a larger budget. To select a non-default shell location, supply SessionConfig.executable.

Step-by-step tutorial¶

Setup and backend selection¶

Chapters¶