Skip to main content

Flyshell

Python Version Licence Platform Dependencies Tests

Documentation last updated: v1.3.0

A modular, zero-dependency command-line environment and extensible runtime interface built in Python.

Flyshell provides a modular, extensible shell environment featuring dynamic runtime plugin loading, session persistence, secure authentication, and cross-platform process isolation, using only Python standard libraries.

No extra packages required, just install and enjoy!

Key Features

  1. Zero External Dependencies - Flyshell is built entirely with native Python modules with absolutely zero third-party packages required to enjoy full functionality.
  2. Dynamic Plugin Architecture: Flyshell employs a dynamic plugin architecture that automatically scans for plugins in the User Directory following the standard defined in src/flyshell/abstract/base_plugin.py.
  3. Secure Authentication: Flyshell uses salted PBKDF2 HMAC (SHA-256, 600,000 iterations) with constant-time equality comparisons to prevent timing attacks on password information.
  4. Cross-Platform Support: Flyshell is fully supported by Windows (NT), macOS (Darwin) and Linux installations with native OS management and POSIX-aware parsing. Note that Flyshell is not supported by any other systems.
  5. State and History Persistence: Flyshell has a fully encapsulated SQL storage system using SQLite3 providing session metrics and ISO 8601 UTC audit logging.

System Requirements

  1. Python: Your Python installation or IDE must support Python 3.10 or newer as Flyshell utilises structural pattern matching features. Older Python installations will be rejected by Flyshell on boot or could crash the system.
  2. Operating System: Your operating system must be Windows 10/11, macOS (Darwin) or Linux. Any other operating system will be rejected by Flyshell on boot.

System Architecture

src/
└── flyshell/
    ├── abstract/
    │   ├── __init__.py
    │   ├── base_cmd.py
    │   ├── base_plugin.py
    │   └── parent_cmd.py
    ├── builtin/
    │   ├── __init__.py
    │   ├── diskops.py
    │   ├── fs.py
    │   ├── pkg.py
    │   ├── system.py
    │   └── utils.py
    ├── core/
    │   ├── __init__.py
    │   ├── auth.py
    │   ├── console.py
    │   ├── data.py
    │   ├── deps.py
    │   ├── directory.py
    │   ├── env.py
    │   └── loader.py
    ├── __init__.py
    ├── constants.py
    └── main.py

Installing Flyshell

There are two methods to install Flyshell.

Method 1: Install via pip (Best for General Use)

Install Flyshell through pip:

pip install flyshell

Then, you can simply run Flyshell:

flyshell

Method 2: Install from source via git (Best for Development & Custom Plugins)

Clone the GitHub repository:

git clone https://github.com/kianodev/flyshell.git

Switch to the Flyshell directory and install in editable mode:

cd flyshell
pip install -e .

After this, you can simply run Flyshell:

flyshell

Adding optional dependencies

To install Readline (on Windows):

pip install -e .[readline]

To install the development and testing suite (including Pytest):

pip install -e .[dev]

Exploring Flyshell

Once you have installed Flyshell using either of the methods above, you will be prompted to initialise your user profile. Once this is complete, you will be greeted with a prompt that looks like this:

Flyshell [v1.x.x] (current_dir)>>

From this stage, you can enter a wide variety of commands. To see the commands list for your installation, type cmds or help to return a full up-to-date directory. Use fs plugins to return plugin information.

Flyshell also supports command chaining out of the box. Use ; to chain commands together regardless of result, && to execute only on success and || to execute only on failure.

Use -h or --help after any command to return that command's specific help list.

To close Flyshell once you are done, enter kill onto the command line then confirm, or press Ctrl + D / Ctrl + Z (different keybinds depending on your host configuration) to close the session immediately.

Creating Custom Plugins

Flyshell features an extensible plugin API. This API supports both single-file and multi-file plugins. Follow the below guide to create your own.

Plugins must inherit from the BasePlugin contract defined in src/flyshell/abstract/base_plugin.py. Plugins are stored in the User Directory. Navigate to your App Storage folder:

  • Windows: %APPDATA%\Flyshell\plugins
  • macOS: ~/Library/Application Support/Flyshell/plugins
  • Linux: ~/.local/share/Flyshell/plugins

Place your plugins inside the plugins/ folder.

All plugins should define the required attributes. Flyshell can read this information for both fs plugins and [my_plugin] -h / --help which are both supported out of the box. Flyshell will discover, inspect and import your plugin from the plugins/ folder without you having to alter any internal code.

The Entry-Point

All plugins must have an entry-point file. For single-file plugins, this is the plugin file. For multi-file plugins, this file must be named plugin.py and stored directly inside of your plugin's own folder.

This file is what enables Flyshell to speak to your plugin.

# Entry-point (my_plugin.py or my_plugin\plugin.py)

from flyshell import BasePlugin # This is required

class MyPlugin(BasePlugin):
	name = "My Plugin" # The name you want visible to Flyshell
	description = "This is my plugin." # A short one-line explaining what your plugin does
	version = "1.0.0" # Default is 1.0.0
	author = "kianodev" # You can put your name, your GitHub handle, or leave blank to make it 'Unknown'
	usage = "" # (OPTIONAL) Explain how to use your plugin
	extended_help = "" # (OPTIONAL) A more detailed, multi-line guide containing specific assistance
	api_keys = [] # (OPTIONAL) Define any required key names here. Use get_api_key(key_name) to call the key. Please add all keys in CAPITALS.
	third_pty_libs = [] # (OPTIONAL) Define all required third party libraries / dependencies here. Use their Python import names as this is how Flyshell checks them.
	
	def on_load(self): # (OPTIONAL) Enables your program to handle specialist set-up tasks before execute()
		pass

	def on_unload(self): # (OPTIONAL) Enables your program to handle specialist shut-down tasks
		pass

	def execute(self, args): # This is what Flyshell calls to execute
		print(f"Hello! Arguments: {args}")
		return

Extra Functions

Additional functions are available for you to use:

  1. get_data(key, default=None): Retrieves a value from local plugin memory.
  2. set_data(key, value): Updates a key in local memory and automatically persists it to SQLite via save_storage().
  3. load_storage(): Reloads fresh key-value pairs directly from SQLite into self.storage.
  4. save_storage(): Writes all in-memory key-value pairs in self.storage back to SQLite.
  5. get_api_key(key): Fetches the specified API key from flyshell_keys.env.

Plugins save automatically on shut-down.

Built-in Attributes

Every plugin has direct access to the following instance variables:

  • self.plugin_name (str): The unique name identifier used to invoke the plugin.
  • self.storage (dict): In-memory key-value data automatically loaded from the persistent database.
  • self.context (dict): Environmental metadata provided at start-up, within it:
    • self.context["metadata"]["host_os"]: Operating system (e.g., 'Windows', 'Linux', 'Darwin').
    • self.context["metadata"]["version"]: Current Flyshell version.
    • self.context["file_path"]: Full path to the plugin's source file.

Extra Notes

You are welcome to catch errors yourself. However, Flyshell will handle them automatically. That said, if you would like your plugin to continue after an error, you need to implement error handling yourself as the default system closes your plugin.

Metadata

Release files for flyshell 1.3.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for flyshell 1.3.3
File Size Uploaded Provenance Actions
flyshell-1.3.3.tar.gz 36.8 kB With provenance Details for flyshell-1.3.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for flyshell 1.3.3
File Interpreter ABI Platform Actions
flyshell-1.3.3-py3-none-any.whl Python 3 none any Details for flyshell-1.3.3-py3-none-any.whl

Total release size: 71.6 kB

Release files / flyshell-1.3.3.tar.gz

Download URL flyshell-1.3.3.tar.gz
Size 36.8 kB
Tags Source
SHA-256 checksum
How to use checksums
ab4fbde1e9945afb8e4aebea42bd88a5a1d6a8b9c96cfb59273bd09aecf39433
BLAKE2b-256 checksum
How to use checksums
af7534a2bfcaad1fdaf4aadc5ca3e2ed8b26e3e9f8a2cde4c4e07bbd99c13096
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / flyshell-1.3.3-py3-none-any.whl

Download URL flyshell-1.3.3-py3-none-any.whl
Size 34.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b42e8df7600d7a4cce2bef35a89bc41f444de3880a4783b0e2f184e4ff2d88e3
BLAKE2b-256 checksum
How to use checksums
977a4bac93651362404b456a911924a9be1f6f865aba7f376f8dfba503d5611a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for flyshell 1.3.3

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for flyshell-1.3.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

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.

Release history Release notifications | RSS feed

This release

1.3.3 This release

2 release files Full provenance

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