phoenixnebula-cli 1.0.3

A feature-rich, customizable Unix shell with themes and job control

PhoenixNebula 🐚

A feature-rich, customizable Unix shell implementation written in Python with theme support, job control, and comprehensive command handling.

Features ✨

• Interactive Command Execution - Full support for executing system commands with proper I/O handling
• Theme Support - 5 built-in themes (Dracula, Solarized Dark, Nord, Monokai, Gruvbox) plus custom themes
• Job Control - Background and foreground job management with jobs, fg, and bg commands
• Pipeline Support - Chain commands using the pipe operator (|)
• Output Redirection - Redirect output and error streams to files (>, >>, 2>, 2>>)
• Command Aliases - Create and manage command aliases
• History Management - Full command history with persistence and custom history files
• Tab Completion - Smart tab completion for commands and file paths
• Signal Handling - Proper handling of SIGINT, SIGTSTP, SIGQUIT, and SIGWINCH
• PTY Support - Interactive programs (vim, git, ssh, etc.) run with proper terminal control
• Security - No external dependencies, safe input handling, no eval/exec

Installation 📦

Via pip (Recommended)

pip install phoenixnebula-cli
phoenixnebula

Via git + setup.py

git clone https://github.com/SysTechSalihY/phoenixnebula.git
cd phoenixnebula
sudo python3 setup.py install
phoenixnebula

Via Docker

docker pull nobodydeveloper/phoenixnebula:latest
docker run -it nobodydeveloper/phoenixnebula:latest

Binary Distribution 🛠️

PhoenixNebula can be distributed as a standalone binary, so users can run it without installing Python.

Build with PyInstaller (Recommended)

Install PyInstaller:

pip install pyinstaller
git clone https://github.com/SysTechSalihY/phoenixnebula.git
cd phoenixnebula
pyinstaller --onefile phoenixnebula/phoenixnebula.py
Run it directly: ./dist/phoenixnebula

### From source (Development)

```bash
git clone https://github.com/SysTechSalihY/phoenixnebula.git
cd phoenixnebula
pip install -e .
phoenixnebula

Quick Start 🚀

Basic Commands

$ echo "Hello, World!"
Hello, World!

$ pwd
/home/user

$ cd Documents

$ ls -la

Background Jobs

Append & to run a command in the background:

$ sleep 100 &
[1] 12345

$ jobs
[1]  Running  sleep 100

$ fg %1

Piping Commands

$ cat file.txt | grep "search_term" | wc -l

Output Redirection

$ echo "text" > output.txt          # Write to file
$ echo "text" >> output.txt         # Append to file
$ command 2> errors.txt             # Redirect stderr
$ command 2>> errors.txt            # Append stderr

Themes

$ theme list
Available themes:
  - dracula *
  - nord
  - solarized_dark
  - monokai
  - gruvbox

$ theme set nord
Theme applied: Nord

Configuration 🎨

Shell Configuration File

Create ~/.phoenixnebularc for aliases and settings:

alias ll=ls -la
alias ..=cd ..
alias gs=git status
export PS1="\u@\h \w\$ "

Themes

PhoenixNebula comes with 5 built-in themes. Create custom themes at ~/.phoenixnebula/themes/mytheme.json:

{
  "name": "My Custom Theme",
  "background": "#1e1e1e",
  "foreground": "#e0e0e0",
  "cursor_color": "#e0e0e0",
  "black": "#000000",
  "red": "#ff0000",
  "green": "#00ff00",
  "yellow": "#ffff00",
  "blue": "#0000ff",
  "purple": "#ff00ff",
  "cyan": "#00ffff",
  "white": "#ffffff",
  "bright_black": "#808080",
  "bright_red": "#ff8080",
  "bright_green": "#80ff80",
  "bright_yellow": "#ffff80",
  "bright_blue": "#8080ff",
  "bright_purple": "#ff80ff",
  "bright_cyan": "#80ffff",
  "bright_white": "#ffffff",
  "prompt_user": "#00ff00",
  "prompt_host": "#00ffff",
  "prompt_path": "#ffff00",
  "prompt_symbol": "#ff00ff"
}

Then apply it:

$ theme set mytheme

Built-in Commands 💻

Navigation & Execution

Command	Usage	Description
cd	cd [directory]	Change current directory
pwd	pwd	Print working directory
echo	echo [text]	Print text to output
exit	exit [code]	Exit the shell
type	type <command>	Display command type
clear	clear	Clear terminal screen

Command History

Command	Usage	Description
history	history [n]	Show last n commands
history -r <file>	Load history from file
history -w <file>	Write history to file
history -a <file>	Append history to file

Aliases

Command	Usage	Description
alias	alias	List all aliases
alias [name]=[value]	alias ll='ls -la'	Create alias
unalias	unalias <n>	Remove alias

Environment & Variables

Command	Usage	Description
export	export VAR=value	Set environment variable
unset	unset VAR	Unset environment variable
set	set [VAR=value]	Get/set shell variables

Job Control

Command	Usage	Description
jobs	jobs	List background jobs
fg	fg %jobid	Bring job to foreground
bg	bg %jobid	Resume job in background

Themes

Command	Usage	Description
theme	theme	Show available themes
theme list	List all themes
theme set <n>	theme set dracula	Apply theme
theme current	Show current theme

Advanced Features 🔧

Pipeline Operations

Chain multiple commands with pipes:

$ cat data.txt | sort | uniq | wc -l

Variable Expansion

Expand environment variables:

$ echo $HOME
/home/user

$ echo ${PATH}
/usr/local/bin:/usr/bin:/bin

Tilde Expansion

Home directory shortcut:

$ cd ~/Documents
$ cat ~/.bashrc

Interactive Programs

The shell automatically detects and runs interactive programs with proper terminal control:

$ vim file.txt
$ git commit
$ python3

Security 🔒

• No External Dependencies - Uses only Python standard library
• Safe Input Handling - All input is validated and parsed safely using shlex
• No Code Injection - Never uses eval(), exec(), or __import__()
• Secure Variable Expansion - Variables are safely expanded with fallbacks
• Signal Safety - Proper signal handling without race conditions
• Process Isolation - Background jobs properly isolated using process groups

See SECURITY.md for detailed security information.

Testing 🧪

Run the comprehensive test suite:

# Install test dependencies
pip install pytest pytest-cov

# Run all tests
pytest tests/ -v

# Run with coverage report
pytest tests/ -v --cov=phoenixnebula

# Run specific test class
pytest tests/test_phoenixnebula.py::TestSecurityInputValidation -v

Project Structure 📁

phoenixnebula/
├── phoenixnebula/
│   ├── __init__.py
│   └── phoenixnebula.py
├── tests/
│   └── test_phoenixnebula.py
├── Dockerfile
├── Dockerfile.prod
├── docker-compose.yml
├── setup.py
├── setup.cfg
├── pyproject.toml
├── MANIFEST.in
├── README.md
├── LICENSE
└── .gitignore

Keyboard Shortcuts ⌨️

• Ctrl+C - Cancel current command
• Ctrl+Z - Suspend current command
• Ctrl+D - Exit shell (EOF)
• Tab - Auto-complete command or file path
• Up/Down Arrows - Navigate command history
• Ctrl+R - Reverse history search (if supported)

Environment Variables 🌍

Variable	Description
PATH	Search path for executables
HOME	User's home directory
HISTFILE	Location of command history file
SHELL	Current shell name
USER	Current user name
HOSTNAME	System hostname

Troubleshooting 🔧

Shell Exits Unexpectedly

Check your ~/.phoenixnebularc file for errors:

cat ~/.phoenixnebularc

History Not Saving

Ensure the history file location is writable:

export HISTFILE=~/.phoenixnebula_history

Tab Completion Not Working

Verify Python readline module is available:

python3 -c "import readline; print('readline available')"

Interactive Programs Not Working Properly

Ensure your terminal emulator supports ANSI escape codes and PTY operations. Try clearing the screen:

clear

Theme Colors Not Applying

Try resetting the terminal:

reset
phoenixnebula

Contributing 🤝

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License 📜

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments 🙏

• Inspired by bash, zsh, and other Unix shells
• Theme colors from popular terminal themes
• Built with Python's standard library

Support 💬

For issues, questions, or suggestions:

1. Check existing GitHub Issues
2. Create a new issue with detailed description
3. Submit a Pull Request with improvements

Security Policy 🔐

If you discover a security vulnerability, please email [e-mail] instead of using the issue tracker.

---

Enjoy using PhoenixNebula! 🎉

For more information and advanced usage, visit the GitHub repository.