What is OmniShell
OmniShell is a Python-based shell made with moddablity, configurability, and extensibility in mind.
A quick warning: this is my first big code project and OmniShell is nowhere near complete and I still have many planned features, so please keep this in mind before using it.
But now that that's out of the way, it's time to talk features!
Features
- Ability to add Python files as shell commands, e.g. instead of
python ~/OmniShell/scripts/themetool.pyyou can simply runthemetool - A nice theme engine
- Easily configurable
- Cross-platform
- Windows
- Linux
- MacOS (currently untested -- I don't have a Mac)
- Extensible
- Uses your current shell as a base and extends apon it
Requirements
- Python 3
- Rich
Planned features
| Feature | In Development | How Complete |
|---|---|---|
| Tab Completion | No | 0% |
| Command Highlighting | No | 0% |
| File Conflict Selection | No | 0% |
| Shell Selection | No | 0% |
| Running Lines of Python | No | 0% |
Installation
On Windows
The basic installation on Windows is basically the same as on any other operating system, simply download the latest release zip and extract it, then run boot.py. However if you don't want to have to run the Python file every time you want to use Omnishell there are many workarounds depending on your terminal.
If you use Windows Terminal:
If you use Windows Terminal the process is quite simple:
- Open Windows Terminal and open the settings tab using the menu or by pressing
CTRL+, - Next scroll down to the bottom of the sidebar and press the
+icon and click+ New empty profile - Now click
Starting directoryand select the path to your OmniShell directory (the one that containsboot.py) - After that click
Command lineand select yourpython.exe. If you don't know where this is, there is a great guide on how to locate it here - Now add
boot.pyon the end of the command line field so it ends up looking similar to this:[path to python.exe]\python.exe boot.py - Finally, add any finishing touches to your OmniShell profile and, if you want, set it as the default profile
If you use Fluent Terminal:
If you use Fluent Terminal the process is incredibly similar to the setup on Windows Terminal:
- Open Fluent Terminal and open the settings window using the menu or by pressing
CTRL+SHIFT+, - Next click the
Profilesbutton on the sidebar and click the+ Create newbutton - Now in the
Working directoryfield select the path to your OmniShell directory (the one that containsboot.py) - After that in the
Shell executable locationfield select yourpython.exe. If you don't know where this is there is a great guide on how to locate it here - Now in the arguments field put
boot.py - Finally add any finishing touches to your OmniShell profile and, if you want, set it as the default profile
If you use Cmder:
If you use Cmder the process is slightly different to the other terminals, but is still very easy to set up:
- Open Cmder and open the settings window using the menu or by pressing
WIN+ALT+p - Next expand the
Startupsection on the side bar by pressing the+icon, and then clickTasks - Then click the
+icon, and after that clickFile path...and selectboot.py - Now click the
Startup dir...button select the path to your OmniShell directory (the one that containsboot.py) - Finally add any finishing touches to your OmniShell task and, if you want, set it as the default task, and remember to click
Save settings
On Linux
The basic installation on Linux is basically the same as on any other operating system: simply download the latest release zip, and extract it, then run boot.py. Sadly I don't really know how to make it work on Linux quite as well as it works on Windows, e.g. start automatically on a new terminal instance, so if you have an idea of how I could implement this or even actually have it set up and working, please tell me in the issues how you did it, so I can put it here.
On MacOS
The basic installation on MacOS is basically the same as on any other operating system: simply download the latest release zip, and extract it, then run boot.py. Please keep in mind that this won't make OmniShell start when a new terminal instance is opened. Sadly I don't know how to set this up on MacOS, and neither can I test or find a solution, as I don't have a Mac. However if you do have a way to do this, then please tell me in the issues, so I can add it here.
Usage
How to add commands
So you want to add custom commands to OmniShell? Don't worry, this is something I kept in mind the entire time while developing OmniShell, making sure to keep it quick and simple!
- First enter the
scriptsdirectory in the root of your OmniShell folder (the one that containsboot.py), and create a new directory called whatever you want the command to be - Now in the directory that you've just created, add a file called:
WHATEVER_YOU_CALLED_THE_DIRECTORY.py,WHATEVER_YOU_CALLED_THE_DIRECTORY.bat,WHATEVER_YOU_CALLED_THE_DIRECTORY.exeorWHATEVER_YOU_CALLED_THE_DIRECTORY.lnk - And thats it!
How to contribute!
So you would like to extend the functionality, or improve the looks of your OmniShell? Well, you are in the right section of the docs, my friend. In this section I will be going over how to make extensions, themes, and scripts for OmniShell.
How to make themes
So you would like to make a theme for Omnishell? Don't worry, this is very easy and this guide will walk you through how to make a theme, and get your OmniShell looking sexy in no time!
Now, before we begin, this guide will show you how to make and apply your theme using the theme tool that comes packaged with OmniShell, you can apply themes without the use of the tool but it is not recommended.
- First enter the
themesdirectory in your root OmniShell folder (the one that containsboot.py), and create a new directory called whatever the name of your theme will be - Now enter the directory you just created and make a new file called
theme.py - Next open
theme.pyin your preferred editor, and create three new variables calledinfo,logo, andprompt, so it looks like this:
info = """"""
logo = """"""
prompt = """"""
- Set the
logovariable as your logo; this could be ASCII art, an ASCII banner, or any other string. It should look something like this:
info = """"""
logo = """ _ _
/ \ | | ___ __ _ ___
/ _ \ | | / _ \ / _` |/ _ \
/ ___ \ | |__| (_) | (_| | (_) |
/_/ \_\ |_____\___/ \__, |\___/
|___/"""
prompt = """"""
- Set the
promptvariable to your prompt. It should look something like this:
info = """"""
logo = """ _ _
/ \ | | ___ __ _ ___
/ _ \ | | / _ \ / _` |/ _ \
/ ___ \ | |__| (_) | (_| | (_) |
/_/ \_\ |_____\___/ \__, |\___/
|___/"""
prompt = """A
Prompt
can
be
multi
line> """
- Nearly done! Set the info variable to any info you would like users to know about your theme, e.g. the name of the author and the inspiration for the theme. This will be printed when selecting a theme. Your file should now look like this:
info = """TEST THEME
This is a test theme to demonstrate how to create themes
By: D1j1t"""
logo = """ _ _
/ \ | | ___ __ _ ___
/ _ \ | | / _ \ / _` |/ _ \
/ ___ \ | |__| (_) | (_| | (_) |
/_/ \_\ |_____\___/ \__, |\___/
|___/"""
prompt = """A
Prompt
can
be
multi
line> """
- Add finishing touches. Remember that all these variables are printed with rich so you can do some fancy stuff. Here are some ideas:
- You can use Unicode characters like this:
u"\uCHARACTERCODE", e.g. for█writeu"\u2588" - You can use coloured, bold, italic, and blinking text like this
- You can use variables in your prompt, logo, or info to make user customization easy, e.g.:
animal = "cow" prompt = (animal + " = best animal> ")- You can use Python modules to put things like the time or battery percentage into the prompt, logo, or info, e.g.:
from datetime import datetime now = datetime.now() prompt = ("the time is: " + now.strftime('%H:%M:%S') + " > ")- Here is a simple yet powerful trick to improve the look and usablity of the prompt: add
\nas the first thing in thepromptvariable to add spacing in between prompts, e.g.prompt = """\nAPrompt> """
- You can use Unicode characters like this:
- Your theme is now complete. Apply it with
themetooland gaze in awe at your new theme!
How to make extensions
If you want to extend the functionality or add features to OmniShell then you might want to use extensions. This section will explain how to make and apply extensions.
However before we start there is an issue: different extensions do different things, the solution is that this guide will only show you how to set up environments to make extensions in, and apply the extensions you have made.
- First enter the
scriptsdirectory in the root of your OmniShell folder (the one that containsboot.py), and create a new directory called whatever you want the command to run your extension to be - Now in the directory that you've just created, create a file called
WHATEVER_YOU_CALLED_THE_DIRECTORY.py - Next write your extension in the
.pyfile you've just created - If you want the extension to run at startup of OmniShell, then put
exec(open('</PATH/TO/PY/FILE>').read())somewhere in your.omnirc.pyfile - Now go and make kick-ass extensions, and show the true power of OmniShell!
Strut your stuff
You've made your themes and extensions, and you're ready to release them to the world. However, you want people to find them easily and gaze in awe at your readme. Well, don't worry, I have provided all of the OmniShell branding in a separate repo here. However, I also have some tips!
If you are releasing a theme
- Use this badge at the top of your
README.mdif you are unsure with markdown syntax simply put this at the top or under your logo
 - And use the
#omnishelland#omnishell-themetags on github
If you are releasing an extension
- Use this badge at the top of your
README.mdif you are unsure with markdown syntax simply put this at the top or under your logo
 - And use the
#omnishelland#omnishell-extensiontags on github
That's All Folks
I'll add more if I think of anything or if anyone has any good suggestions! :)