🐚 ShellKit (libc + pysh)
Learn how
echoworks from shell to syscall — all in one Python playground.
📖 Overview
ShellKit is a Unix-like educational terminal toolkit consisting of two main components:
- Libc: A Python-based simulation of core C library calls such as
syscall,write, andprintf. It walks through the transition from user space to kernel space. - Pysh: An interactive shell built on top of
Libc, featuring internal commands, REPL execution, cross-layer tracing, and multilingual support. Designed for system developers and terminal enthusiasts.
Runs on both macOS and Linux, supporting Arm64 and Intel x86_64 architectures.
✨ Features
Pysh
- 🧠 Built-in commands (
cd,echo,pwd,env, etc.) - 🧵 Multilingual support with full manuals (EN/CH/JP/KR)
- 🔍 Cross-layer tracing: from command parsing → libc functions → C-level syscalls
- 🧹 Composable REPL execution model
- 🔌 Pluggable command registration system
Libc
- 📨 Custom
printfengine with%s,%d,%fformat specifiers and escape sequences - 📜 Native syscall bridge (Python ↔ C) via
syscall/syslib.so - 🧪 Unit-tested via
pytest, with benchmarks for key libc behaviors
📦 Installation
Requires
Python 3.10or newer
Install via pip:
pip install shellkit
After installation, launch the interactive shell with:
pysh
🚀 Usage
pysh [options]
CLI Options
| Option | Description |
|---|---|
--command |
Run a single command |
--no-banner |
Skip the startup banner |
--no-reminder |
Disable rest reminder messages |
--quiet |
Quiet mode with minimal output |
--safe |
Enable safety mode (blocks dangerous commands like rm -rf /) |
--debug |
Enable shell-level debug output |
--trace-echo |
Trace echo/printf calls down to libc syscall layer |
For more, run:
pysh --help
📚 Examples & Tutorials
Want to see ShellKit in action? Check out our comprehensive examples:
→ Examples & Demos - Real terminal sessions from basic to advanced features
Complete with multilingual demos, debugging tutorials, and advanced printf formatting!
📦 Project Structure (partial)
shellkit/
├── native/ # C code for native syscall implementation (builds syslib.so)
├── shellkit/ # Main package
│ ├── syscall/ # Python-side syscall wrappers via ctypes
│ ├── libc/ # Custom libc (printf, write, exit)
│ ├── shell/ # Core engine, built-in commands, runtime, REPL
│ ├── inspector/ # Debugging and tracing tools
│ └── i18n/ # Multilingual dictionaries and support
├── benchmarks/ # Performance benchmarks
├── examples/ # Usage examples and demo logs
└── tests/ # Test suite
🥉 Platform Support for syslib.so
| Platform | Supported | Notes |
|---|---|---|
| Linux x86_64 | ✅ Yes | Uses rax = 1 + syscall |
| Linux ARM64 | ✅ Yes | Uses x8 = 64 + svc #0 |
| macOS Intel (x86) | ✅ Yes | Uses rax = 0x2000004 + syscall |
| macOS ARM64 (M1/M2/M3) | ✅ Yes | Uses syscall(SYS_write, ...) (soft wrapper) |
| Windows | ❌ No | Not supported; lacks a unified syscall() ABI |
📌 Changelog
See CHANGELOG.md for version history.
📜 License
MIT License. See LICENSE for details.
🤝 Acknowledgments
Inspired by the spirit of classic Unix shells.
Thanks to all system programmers and terminal geeks who paved the way.
Metadata
Release files for ShellKit 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 5.0 MB
Release files / shellkit-0.1.0-cp313-cp313-musllinux_1_2_x86_64.whl
| Download URL | shellkit-0.1.0-cp313-cp313-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 209.2 kB |
| Tags | CPython 3.13 Linux musl 1.2+ x86-64 |
|
SHA-256 checksum How to use checksums |
669ede4f562b804478440b899a649a025e2299eb4b14f904b30dcf03f36c9f2b
|
|
BLAKE2b-256 checksum How to use checksums |
8bd92f1062c3cdcfee0baa93ba6935cb817bca43c77cbd0ae7d3137f48837b4c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp313-cp313-musllinux_1_2_aarch64.whl
| Download URL | shellkit-0.1.0-cp313-cp313-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 209.6 kB |
| Tags | CPython 3.13 Linux musl 1.2+ ARM64 |
|
SHA-256 checksum How to use checksums |
7034d3429c2207c740879546dd8edb20500d389bd3b3902924e5300e0b62558d
|
|
BLAKE2b-256 checksum How to use checksums |
79f75e26cc439b705922c84f2ad101718e5d9e0cd17e7f63d9600fa79a64716e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
| Download URL | shellkit-0.1.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 210.0 kB |
| Tags | CPython 3.13 Linux glibc 2.17+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
2dd741cbad1cef8930455c64cf12e41a09238fbe1177639e948f00b28694db02
|
|
BLAKE2b-256 checksum How to use checksums |
a186d42d04d731eb98e205f49b28d30860ed0c60b9654ff6aa17f3d84f5a3a2c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | shellkit-0.1.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 209.1 kB |
| Tags | CPython 3.13 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
b0188671413e5fa7c6a0f5be9a6cadb4f60833513f3b121381128811247959e4
|
|
BLAKE2b-256 checksum How to use checksums |
73d7958a2a1a4ff08f6c872f1e36765a8f0f26ec7106877febf3f653cca1f66d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | shellkit-0.1.0-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 206.3 kB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
e93340c9ab15fe2bde275a8820884c665cdff2b6044fb910fd3da36b09f6f0f8
|
|
BLAKE2b-256 checksum How to use checksums |
6c897a94a7dc39b2f45f8878c7b468efb1df765ce1e636c52837a2d05c0b141f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp313-cp313-macosx_10_13_x86_64.whl
| Download URL | shellkit-0.1.0-cp313-cp313-macosx_10_13_x86_64.whl |
|---|---|
| Size | 205.8 kB |
| Tags | CPython 3.13 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
62781c01ab8f8615c0c697c1bc3bbaa35c27149bf60aeb3da2b14344d5c7c9fc
|
|
BLAKE2b-256 checksum How to use checksums |
4575e3305cb99edc54b420eea418fea937ddbe0219bdbe911b9b433f44b0b3b7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp312-cp312-musllinux_1_2_x86_64.whl
| Download URL | shellkit-0.1.0-cp312-cp312-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 209.2 kB |
| Tags | CPython 3.12 Linux musl 1.2+ x86-64 |
|
SHA-256 checksum How to use checksums |
3719b5fd8685f4ef89dfc5fdb6557472f95b8d144e24fde447ad3d7f635dcbca
|
|
BLAKE2b-256 checksum How to use checksums |
4466d7d78b5ab0419268aaa1e8753acb7087c449e1ee96658556c09d2aced839
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp312-cp312-musllinux_1_2_aarch64.whl
| Download URL | shellkit-0.1.0-cp312-cp312-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 209.6 kB |
| Tags | CPython 3.12 Linux musl 1.2+ ARM64 |
|
SHA-256 checksum How to use checksums |
7644d1ce60bd17d68d919bc3df28d4877d9c3fc6bb63654ad5d479a74f09995d
|
|
BLAKE2b-256 checksum How to use checksums |
bc1d6cf2be91698afb8715231c01c71c003f0cd43c97462d790d93394afa88b5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
| Download URL | shellkit-0.1.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 210.0 kB |
| Tags | CPython 3.12 Linux glibc 2.17+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
7707e37c2c2692ab937105010975350712a8d8275fd548844d50f2629cace926
|
|
BLAKE2b-256 checksum How to use checksums |
ad632d1c4508c7d7d29686803610bff7aa95ece1c03b86adfc8a202aa8c3a40c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | shellkit-0.1.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 209.1 kB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
6d1a8969068ed8466bddd02a70354bd5abfb86e418cf07928d46131d3c6189a5
|
|
BLAKE2b-256 checksum How to use checksums |
f7c13682423baafbe468fe49f13aa8151c72f6d243a4de615cde141099a15391
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | shellkit-0.1.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 206.3 kB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
41b80b20d7a2491dc33ee717fe099994caf0a0a26f05b0b45583225762fe36e9
|
|
BLAKE2b-256 checksum How to use checksums |
dfdaf2b03bd670958283ffafa22fbd79bf2aee6f89707a091cdcf6c901997d14
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp312-cp312-macosx_10_13_x86_64.whl
| Download URL | shellkit-0.1.0-cp312-cp312-macosx_10_13_x86_64.whl |
|---|---|
| Size | 205.8 kB |
| Tags | CPython 3.12 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
cfc3391d0d48dcfc8ea9e922a441ddc8558b6082a32c5aa65ec3511cae8d8e17
|
|
BLAKE2b-256 checksum How to use checksums |
8385bada5a40bb6fd9ddff1b2639982a36419d71769fadc9105d40e2ba64a6b6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp311-cp311-musllinux_1_2_x86_64.whl
| Download URL | shellkit-0.1.0-cp311-cp311-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 209.1 kB |
| Tags | CPython 3.11 Linux musl 1.2+ x86-64 |
|
SHA-256 checksum How to use checksums |
4e96f71bc9395011a77a05b23282182ee81ec5893cdd3b5772c934ebf4f20965
|
|
BLAKE2b-256 checksum How to use checksums |
19b9f0c893c4cf0f83fe89a7a4e1e92e4293a467216bcca8f9e7f229056cd933
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp311-cp311-musllinux_1_2_aarch64.whl
| Download URL | shellkit-0.1.0-cp311-cp311-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 209.6 kB |
| Tags | CPython 3.11 Linux musl 1.2+ ARM64 |
|
SHA-256 checksum How to use checksums |
b36c633e55667b3b44eaccdaab51ae8ec96a66b9e189835d10bc7f4dfcd35f6a
|
|
BLAKE2b-256 checksum How to use checksums |
10a6deee4580170fad6763a59e908f5705ff00f19f2c5f28c3bdf2a9ab7a5fbc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
| Download URL | shellkit-0.1.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 210.0 kB |
| Tags | CPython 3.11 Linux glibc 2.17+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
ceb843ac1b27413fb9030d85edf8f9ab02b0e4d823170cd6014b9da75d5ffc46
|
|
BLAKE2b-256 checksum How to use checksums |
de57db8630a2ca511013069de135dd2c13ff772755c3ade94fc871aad42a607f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | shellkit-0.1.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 209.1 kB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
3537b0609ea618edd5746a3a8c86db3d9b8cdfae18ec77d60916da841f8b85d5
|
|
BLAKE2b-256 checksum How to use checksums |
76cded95f68d99cda8fab907f769eb583f2f0b43cde5a64b7f321ab15ffaf0ed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | shellkit-0.1.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 206.3 kB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
7207bdf63de9bb368cfc3d654e497a44b08c23d69fbceed4eab8175d58ed9fb2
|
|
BLAKE2b-256 checksum How to use checksums |
aff8e6b8f3b452f33a216414be81844fb97b787e9e056a30d3b86f0adefa8433
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp311-cp311-macosx_10_9_x86_64.whl
| Download URL | shellkit-0.1.0-cp311-cp311-macosx_10_9_x86_64.whl |
|---|---|
| Size | 205.8 kB |
| Tags | CPython 3.11 macOS 10.9+ x86-64 |
|
SHA-256 checksum How to use checksums |
c8f08a66c9f483b741d6e1d413f11a4b39df9a559c1d0d6607896a3c73008784
|
|
BLAKE2b-256 checksum How to use checksums |
d9e9aae19b119c560bd944fef29ab5bd45fdfb03c18093d365f044cfecab8ef7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp310-cp310-musllinux_1_2_x86_64.whl
| Download URL | shellkit-0.1.0-cp310-cp310-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 209.1 kB |
| Tags | CPython 3.10 Linux musl 1.2+ x86-64 |
|
SHA-256 checksum How to use checksums |
c1ba205b21acba8d02dba417f53ca1b0f2b537899e1ee9da7a34a53d081cbdae
|
|
BLAKE2b-256 checksum How to use checksums |
f84c6f9b69d6952ec6c09f0a3916d3dc830a822fde25f00a70325b3e96207427
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp310-cp310-musllinux_1_2_aarch64.whl
| Download URL | shellkit-0.1.0-cp310-cp310-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 209.6 kB |
| Tags | CPython 3.10 Linux musl 1.2+ ARM64 |
|
SHA-256 checksum How to use checksums |
4931330e26173d9405cb9d6a0dc6c1c521e39c0b95ed0eaa1de7c8e675ddc77c
|
|
BLAKE2b-256 checksum How to use checksums |
a277d545cf68dec21a3dedb0a9c150e4f2959804a565dad7858aead6c78d6871
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
| Download URL | shellkit-0.1.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 210.0 kB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
0c40b8f2c58410e3675625b9ae66e89e76049c2e73b6989500de470405e46a5e
|
|
BLAKE2b-256 checksum How to use checksums |
96363e4da414c2f22f6c469c76cce6252c9487bcc01cc397abf793a8f8724239
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | shellkit-0.1.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 209.1 kB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
c01f7545ce7c0a900eece2775f652f2e6280564d8933a1e7db1cd8680fa1e658
|
|
BLAKE2b-256 checksum How to use checksums |
ef7e1d953bba0e43877b97fe6f42623f6d7c1cb27876382961b44833f5c53219
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | shellkit-0.1.0-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 206.3 kB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
cb6a9de64353aa803ffb3057ca90c1db227bd97f0dc6b0a3370a3ee791ad60fa
|
|
BLAKE2b-256 checksum How to use checksums |
ea8474ef16e16130d5ac14377194edff6d9b4a1804a6353bcec0691daf89aac0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / shellkit-0.1.0-cp310-cp310-macosx_10_9_x86_64.whl
| Download URL | shellkit-0.1.0-cp310-cp310-macosx_10_9_x86_64.whl |
|---|---|
| Size | 205.8 kB |
| Tags | CPython 3.10 macOS 10.9+ x86-64 |
|
SHA-256 checksum How to use checksums |
c0c11b6d8e8a9f56dd8f122cc44082f84028d0a0f7d670d7f21bb274d26a9010
|
|
BLAKE2b-256 checksum How to use checksums |
efbb7021b058b3dbcf806153400e382150ca030d90ceb1523985c5ed24cb8609
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Security for ShellKit 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.