Pre-release

This release is a pre-release and may not be stable for production use.

shell-use (Python)

Python bindings for shell-use; a terminal automation, inspection, assertion, and recording engine written in Rust.

Install

pip install shell-use

Requires Python 3.8+. Wheels are published for common platforms via maturin

Quick start

import asyncio
from shell_use import ShellUse

async def main():
    async with ShellUse() as su:
        await su.open()
        await su.submit("echo hello")
        await su.wait_command()
        await su.expect_text("hello")
        await su.expect_exit_code(0)

asyncio.run(main())

Drive a full-screen TUI:

async with ShellUse("vim-session") as su:
    await su.run("vim", "file.txt")
    await su.wait_idle()
    await su.press("i")
    await su.type("some text")
    await su.press("Escape", ":", "w", "q", "Enter")
    await su.wait_exit()

Errors

Every failure maps to one of the engine's error kinds:

Exception Exit code Meaning
ExpectationError 1 an expect/wait condition was not met
UsageError 2 invalid argument (e.g. a bad regex)
NoSessionError 3 no active session
InternalError 5 internal engine error

All derive from ShellUseError. wait_* and expect_* raise ExpectationError on failure. Assertion errors include the current visible terminal content.

API

ShellUse(session="default", *, timeouts=None, artifacts=None) mirrors the cli: open / run, type / write, submit, press / keys, mouse.click|move|down|up|drag|scroll, resize, signal / kill, state, text, cells, get_command / get_output / get_exit_code / get_cwd / get_cursor / get_size, screenshot, wait_text / wait_idle / wait_command / wait_exit / wait_ready, expect_text / expect_exit_code / expect_output / expect_snapshot, close, and close_quiet.

Module-level helpers: sessions(), close_all(), get_recording(), unique_session().

open() and run() accept wait_ready=, retries=, and timeouts=. The timeout classes are text, idle, command, exit, and ready; timeouts= sets session defaults, the constructor takes the same Timeouts (or a dict) as a client-wide default. Unknown class names raise.

ShellUse.ephemeral(prefix=None, **kwargs) binds a client to a unique, process-local session name. artifacts={"dir": ..., "on_failure": ...} attaches the terminal contents to an ExpectationError.

shell_use.testing has helpers for terminal tests: create_terminal, terminal (an async context manager), close_all_tracked, DEFAULT_SHELL, and terminal_snapshot.

from shell_use.testing import terminal

async def test_echo():
    async with terminal() as t:
        await t.submit("echo hi")
        await t.wait_command()
        await t.expect_text("hi")

Each terminal is uniquely named, so parallel workers don't collide. set_terminal_defaults(...) sets suite-wide options (timeouts, artifacts, ...).

Cancellation and recordings

Cancelling a task does not cancel the underlying Rust operation. Operations for single sessoins wait for completion (ex: close(), close_all()).

Closing a session removes it from sessions(), but keeps its recording. get_recording() can read that recording for the rest of the process. The 1024 most recently closed sessions have their recordings retained.

Configuration

Variable Purpose
SHELL_USE_SESSION default session name
SHELL_USE_TIMEOUT_<CLASS>_MS fallback timeout for one class (TEXT, IDLE, COMMAND, EXIT, READY)

Project links

Data verified by PyPI on Aug 5, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for msft_cpendery from gravatar.com msft_cpendery

Credits

Author: Microsoft

GitHub Statistics

Data verified by PyPI on Aug 5, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.8

Tags

terminal pty automation testing tui shell-use

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

shell_use-0.0.1b6.tar.gz (1.7 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

shell_use-0.0.1b6-cp38-abi3-win_arm64.whl (3.3 MB view details)

Uploaded CPython 3.8+Windows ARM64

shell_use-0.0.1b6-cp38-abi3-win_amd64.whl (3.4 MB view details)

Uploaded CPython 3.8+Windows x86-64

shell_use-0.0.1b6-cp38-abi3-musllinux_1_2_x86_64.whl (3.5 MB view details)

Uploaded CPython 3.8+musllinux: musl 1.2+ x86-64

shell_use-0.0.1b6-cp38-abi3-musllinux_1_2_aarch64.whl (3.4 MB view details)

Uploaded CPython 3.8+musllinux: musl 1.2+ ARM64

shell_use-0.0.1b6-cp38-abi3-manylinux_2_28_x86_64.whl (3.3 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.28+ x86-64

shell_use-0.0.1b6-cp38-abi3-manylinux_2_28_aarch64.whl (3.2 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.28+ ARM64

shell_use-0.0.1b6-cp38-abi3-macosx_11_0_arm64.whl (3.1 MB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

shell_use-0.0.1b6-cp38-abi3-macosx_10_12_x86_64.whl (3.2 MB view details)

Uploaded CPython 3.8+macOS 10.12+ x86-64

File details

Details for the file shell_use-0.0.1b6.tar.gz.

File metadata

  • Download URL: shell_use-0.0.1b6.tar.gz
  • Upload date:
  • Size: 1.7 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for shell_use-0.0.1b6.tar.gz
Algorithm Hash digest
SHA256 6e89c122f2281931bbae0963ab14892745f5a2afd30d957d8bfb3af61719f952
MD5 fafa9a17c044f7d52c5a0fea4bf58dfd
BLAKE2b-256 42ace26ddfb39eec11d7132667c125c9b18cbdd308f347c970d9ebebb6dd36d6

See more details on using hashes here.

Provenance

The following attestation bundles were made for shell_use-0.0.1b6.tar.gz:

Publisher: release.yml on microsoft/shell-use

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file shell_use-0.0.1b6-cp38-abi3-win_arm64.whl.

File metadata

  • Download URL: shell_use-0.0.1b6-cp38-abi3-win_arm64.whl
  • Upload date:
  • Size: 3.3 MB
  • Tags: CPython 3.8+, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for shell_use-0.0.1b6-cp38-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 8ae62b450f8ac32bcbc670a2b1f74350aa09dd6ecebc81dd1f735f5125f48feb
MD5 b0994b811b220de7b5eab111006d13d6
BLAKE2b-256 adf691ffec64137e134923fd020f92adf2909f216803b3a3de630af78464871f

See more details on using hashes here.

Provenance

The following attestation bundles were made for shell_use-0.0.1b6-cp38-abi3-win_arm64.whl:

Publisher: release.yml on microsoft/shell-use

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file shell_use-0.0.1b6-cp38-abi3-win_amd64.whl.

File metadata

  • Download URL: shell_use-0.0.1b6-cp38-abi3-win_amd64.whl
  • Upload date:
  • Size: 3.4 MB
  • Tags: CPython 3.8+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for shell_use-0.0.1b6-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 3e907a2fe1428a029db67fb3a778b5771a4969ddb82261e01a7b5f21caf8b01e
MD5 33a3380388f8ac08bad71c18cb80ba57
BLAKE2b-256 2eed9b3f5809a83ef968c0462935a01c6d11760456feed3471db62c682f6055b

See more details on using hashes here.

Provenance

The following attestation bundles were made for shell_use-0.0.1b6-cp38-abi3-win_amd64.whl:

Publisher: release.yml on microsoft/shell-use

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file shell_use-0.0.1b6-cp38-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for shell_use-0.0.1b6-cp38-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 d2f82f29b4d3d8f15b35ee4640c08e278e2c9fa2617fbc05ca9e2b81ad48902c
MD5 f301e24dacf3603cf1c569857e275352
BLAKE2b-256 8552bdf3eec077406a443726fe30c13cfd0f53421405e7728c0d99020b577299

See more details on using hashes here.

Provenance

The following attestation bundles were made for shell_use-0.0.1b6-cp38-abi3-musllinux_1_2_x86_64.whl:

Publisher: release.yml on microsoft/shell-use

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file shell_use-0.0.1b6-cp38-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for shell_use-0.0.1b6-cp38-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 f004a30efea956d76f7b977fa0d5d3c33eecc90eccc09ba1a04f81dd9dfd5550
MD5 2e725c9fe405d41ee92b41c5d08e3658
BLAKE2b-256 2f229b29f39362fdbd78453370bbae5e29545b02b3bae8995b045dcc29040062

See more details on using hashes here.

Provenance

The following attestation bundles were made for shell_use-0.0.1b6-cp38-abi3-musllinux_1_2_aarch64.whl:

Publisher: release.yml on microsoft/shell-use

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file shell_use-0.0.1b6-cp38-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for shell_use-0.0.1b6-cp38-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 786608c26c4f59e4c9ed0f8c041961c3112ab283a9fa1dd808b071a11e9bab3b
MD5 f81eb405cca2313bf6bcf1d22ed4e5f2
BLAKE2b-256 fd45aa363c0ab35152e02e09e8612687d260a081dcc5dd6aac2a9b579a629f24

See more details on using hashes here.

Provenance

The following attestation bundles were made for shell_use-0.0.1b6-cp38-abi3-manylinux_2_28_x86_64.whl:

Publisher: release.yml on microsoft/shell-use

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file shell_use-0.0.1b6-cp38-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for shell_use-0.0.1b6-cp38-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 c2e4f2259be97f8fc45a2216918a04d86b7870696cb0048794697c394d4e7e68
MD5 c2137697508820b27bf163410d94ffac
BLAKE2b-256 8934fd39751185884fd25d3882ecb0403379e4f5ecdd19835ddac87766b1116e

See more details on using hashes here.

Provenance

The following attestation bundles were made for shell_use-0.0.1b6-cp38-abi3-manylinux_2_28_aarch64.whl:

Publisher: release.yml on microsoft/shell-use

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file shell_use-0.0.1b6-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for shell_use-0.0.1b6-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 e03da8c17d8f699674a456d745d2c501ce953d2f134441364924fcba7bea8b7a
MD5 ff3e97970e4b5f68e95d963b3684a2ad
BLAKE2b-256 6ac276a8958948ef9c505ec70400510f70d125250b0d78e2b90cfdb2e10fd61e

See more details on using hashes here.

Provenance

The following attestation bundles were made for shell_use-0.0.1b6-cp38-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on microsoft/shell-use

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file shell_use-0.0.1b6-cp38-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for shell_use-0.0.1b6-cp38-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 875145575a38889f2d338dc06f119a64f527794e262869e7ec1482ac690368e6
MD5 9ebc8ae533765a6bb40662b949aba405
BLAKE2b-256 1ebe68203c1f55442d5a4362fd85c47a1305834213ac5f9bffc2971b8c8a0857

See more details on using hashes here.

Provenance

The following attestation bundles were made for shell_use-0.0.1b6-cp38-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on microsoft/shell-use

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

Yanked

0.0.1

2 files

This release
Pre-release

0.0.1b6 This release

9 files

Pre-release

0.0.1b5

2 files

Pre-release

0.0.1b4

2 files

Pre-release

0.0.1b3

2 files

Pre-release

0.0.1b2

2 files

Pre-release

0.0.1b1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page