safectl 0.1.0

Know before you run - A safety wrapper for dangerous shell commands

safe-cli

Know before you run - A safety wrapper for dangerous shell commands

Overview

safe analyzes shell commands before execution, warns you about potential dangers, and helps you avoid costly mistakes.

Part of a developer safety ecosystem:

• scaffold → create projects safely
• safe → run commands safely
• cleaner → clean projects safely
• uterm → undo mistakes safely
• envdoctor → fix broken environments

Features

• 🛡️ Danger Detection: Identifies risky command patterns before execution
• ⚠️ Smart Warnings: Context-aware risk assessment
• 🎯 Interactive Prompts: Beautiful CLI prompts powered by Rich
• 🔍 Dry Run Mode: See what would happen without executing
• 📚 Educational: Learn why commands are dangerous

Installation

pip install safe-cli

Or with Poetry:

poetry add safe-cli

Quick Start

# Analyze and run a command safely
safe rm -rf /tmp/test

# Dry run mode - see what would happen
safe --dry-run rm -rf /tmp/test

# Skip confirmations (useful for scripts)
safe --yes rm file.txt

# Get help
safe --help

Examples

Dangerous File Operations

$ safe rm -rf /
⚠️  CRITICAL DANGER DETECTED
This command will permanently delete files recursively from root directory.
→ Abort / Continue / View Safe Alternative?

Git Operations

$ safe git reset --hard HEAD~5
⚠️  HIGH RISK OPERATION
This will permanently discard uncommitted changes and reset 5 commits.
→ Continue? (y/N)

System Commands

$ safe sudo dd if=/dev/zero of=/dev/sda
⚠️  CRITICAL DANGER DETECTED
This will overwrite disk with root privileges - DATA LOSS IMMINENT
→ Abort / Continue / View Safe Alternative?

Command Coverage (v0.1.0)

Filesystem Operations

• rm - File deletion with recursive and force flags
• mv - File moving with force overwrite detection
• cp - File copying with recursive operations
• chmod - Permission changes (detects dangerous 777/666)
• chown - Ownership changes on system files

Git Operations

• git reset - Detects --hard and commit resets
• git push --force - Warns about force pushes, especially to main/master
• git clean - Prevents accidental deletion of untracked files
• git branch -D - Warns about force-deleting unmerged branches

Docker Operations

• docker system prune - Detects --all and --volumes flags
• docker rm - Container removal with force and volume flags
• docker rmi - Image removal warnings
• docker volume prune - Critical volume data deletion warning

System Commands

• sudo - Detects dangerous command combinations with root
• dd - Warns about disk device overwrites
• kill/killall - Especially with -9 (SIGKILL) flag
• shutdown/reboot - System restart warnings
• mkfs - Filesystem formatting (data destruction)

Development

# Clone the repository
git clone https://github.com/Njau-dev/safe-cli.git
cd safe-cli

# Install dependencies
poetry install

# Run tests
poetry run pytest

# Run with coverage
poetry run pytest --cov

# Format code
poetry run black src tests

# Lint
poetry run ruff check src tests

Architecture

safe-cli/
├── src/safe_cli/
│   ├── cli.py           # Entry point
│   ├── core/            # Core functionality
│   │   ├── parser.py    # Command parsing
│   │   ├── analyzer.py  # Risk analysis
│   │   └── executor.py  # Command execution
│   ├── rules/           # Risk detection rules
│   ├── ui/              # User interface
│   └── utils/           # Utilities
└── tests/               # Test suite

Roadmap

• v0.1.0 (Current): MVP with core safety features
• v0.2.0: Command history and pattern learning
• v0.3.0: Team-wide safety policies
• v0.4.0: Integration with UTerm, Cleaner, EnvDoctor
• v0.5.0: Advanced simulation and dry-run
• v1.0.0: Shell integration and plugin system

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT License - see LICENSE for details.

Ecosystem

Part of the developer safety toolkit:

• scaffold-cli - Project scaffolding
• safe-cli - Command safety (you are here)
• Coming soon: cleaner, uterm, envdoctor

Safety first, always. 🛡️