https://github.com/jimididit/blacksmith
A cross-platform CLI tool that automates the installation of development and cybersecurity toolsets after a fresh OS install.
https://github.com/jimididit/blacksmith
apt automation chocolatey cli cross-platform cybersecurity development-tools devops fresh-install linux package-manager productivity provisioning python setup-automation system-administration windows winget
Last synced: 3 months ago
JSON representation
A cross-platform CLI tool that automates the installation of development and cybersecurity toolsets after a fresh OS install.
- Host: GitHub
- URL: https://github.com/jimididit/blacksmith
- Owner: jimididit
- License: other
- Created: 2025-12-13T21:58:05.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-12-17T04:38:15.000Z (4 months ago)
- Last Synced: 2025-12-20T17:32:08.759Z (3 months ago)
- Topics: apt, automation, chocolatey, cli, cross-platform, cybersecurity, development-tools, devops, fresh-install, linux, package-manager, productivity, provisioning, python, setup-automation, system-administration, windows, winget
- Language: Python
- Homepage:
- Size: 223 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Blacksmith 🔨
> A cross-platform CLI tool that automates the installation of development and cybersecurity tools after a fresh OS install.
[](https://github.com/jimididit/blacksmith/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](https://github.com/jimididit/blacksmith/releases)
[](LICENSE)
[](https://github.com/jimididit/blacksmith)
[](https://github.com/jimididit/blacksmith)
## ✨ Features
- 🎯 **Pre-made tool sets** - Choose from curated sets of development or cybersecurity tools
- 🛠️ **Custom configurations** - Create your own sets or use custom config files
- 🔍 **Unified package search** - Search across all selected managers simultaneously with multi-select support
- 🌐 **Cross-platform sets** - Define sets that work on Windows, Linux, or both with OS-specific manager preferences
- 📦 **Multiple package managers** - Supports apt, yum, pacman, winget, chocolatey, scoop, snap, and flatpak
- 🎯 **Smart manager selection** - Automatically uses preferred package managers with intelligent fallback
- ✨ **Beautiful CLI** - Clean, intuitive interface with progress indicators and helpful feedback
- 🎨 **Custom color scheme** - Elegant purple and cyan theme
- ⚡ **Fast installation** - Automatically detects and uses the best package manager for each tool
- ✅ **Package validation** - Verify package names before installation
- 📤 **Export functionality** - Export sets to native package manager formats (Winget JSON, Chocolatey XML, etc.)
- 🔄 **Update support** - Check for installed packages and update them when available
- 📊 **Set information** - View detailed information about sets including OS compatibility and manager preferences
## 📋 Prerequisites
- Python 3.8 or higher
- One or more supported package managers installed on your system
## 🚀 Quick Start
### Recommended: Install in a Virtual Environment
We recommend installing Blacksmith in a virtual environment to avoid PATH issues and ensure proper isolation.
**1. Create a virtual environment:**
**Linux/macOS:**
```bash
python3 -m venv ~/.blacksmith-venv
source ~/.blacksmith-venv/bin/activate
```
**Windows (PowerShell):**
```powershell
python -m venv $env:USERPROFILE\.blacksmith-venv
$env:USERPROFILE\.blacksmith-venv\Scripts\Activate.ps1
```
**Windows (CMD):**
```cmd
python -m venv %USERPROFILE%\.blacksmith-venv
%USERPROFILE%\.blacksmith-venv\Scripts\activate.bat
```
**2. Install Blacksmith:**
**Option A: Install from PyPI (recommended)**
```bash
pip install jdi-blacksmith
```
**Option B: Install from source**
```bash
git clone https://github.com/jimididit/blacksmith.git
cd blacksmith
pip install -e .
```
**3. Verify installation:**
```bash
blacksmith --version
```
**4. Using Blacksmith:**
After installation, make sure your virtual environment is activated. To activate it again later:
**Linux/macOS:**
```bash
source ~/.blacksmith-venv/bin/activate
```
**Windows (PowerShell):**
```powershell
$env:USERPROFILE\.blacksmith-venv\Scripts\Activate.ps1
```
**Windows (CMD):**
```cmd
%USERPROFILE%\.blacksmith-venv\Scripts\activate.bat
```
**Optional:** Create an alias for easier access:
**Linux/macOS (~/.bashrc or ~/.zshrc):**
```bash
alias blacksmith="$HOME/.blacksmith-venv/bin/blacksmith"
```
**Windows (PowerShell Profile):**
```powershell
Set-Alias blacksmith "$env:USERPROFILE\.blacksmith-venv\Scripts\blacksmith.exe"
```
### Alternative: Install Without Virtual Environment
If you prefer not to use a virtual environment, you can install directly:
```bash
# From PyPI
pip install jdi-blacksmith
# Or from source
git clone https://github.com/jimididit/blacksmith.git
cd blacksmith
pip install -e .
```
> ⚠️ **Note:** Installing without a virtual environment may cause PATH issues. If `blacksmith` is not recognized after installation, you may need to add Python's Scripts/bin directory to your PATH. See the [Troubleshooting Installation](#-troubleshooting-installation) section below.
> 💡 **Having installation issues?** See the [Troubleshooting Installation](#-troubleshooting-installation) section below.
## 📖 Usage
### Quick Command Reference
```bash
# Interactive mode (shows menu)
blacksmith
# List available sets with OS compatibility
blacksmith list
# View detailed set information
blacksmith info
# Install a set
blacksmith install
# Create a custom set
blacksmith create
# Search for packages
blacksmith search [--manager ]
# Export set to native format
blacksmith export --format
# Validate a config file
blacksmith validate
# Uninstall Blacksmith
blacksmith uninstall
```
### Interactive Mode
The easiest way to use Blacksmith is through the interactive menu:
```bash
blacksmith
```
This will display a beautiful banner and an interactive menu to select and install tool sets.
### List Available Sets
View all available sets with OS compatibility indicators:
```bash
blacksmith list
```
The list shows:
- Set name and description
- OS compatibility badges (🪟 Windows, 🐧 Linux, 🍎 macOS)
- Preferred package managers
- Package count
- Compatibility status with your current OS
### Install Pre-made Sets
```bash
# List available sets
blacksmith list
# Install a specific set
blacksmith install development
blacksmith install cybersecurity
blacksmith install minimal
```
### Install from Custom Config
```bash
blacksmith install --file path/to/your-config.yaml
```
### Create Your Own Set
```bash
# Standard mode (cross-platform, multi-manager)
blacksmith create
# Advanced mode (single-OS, single-manager sets)
blacksmith create --advanced
```
This launches an interactive wizard to create a custom tool set configuration. The wizard includes:
- **OS selection**: Choose Windows, Linux, or both for cross-platform sets
- **Manager selection**: Select which package managers to target for each OS
- **Unified search**: Search across all selected managers simultaneously - see results from all managers at once
- **Multi-select**: Select packages from multiple managers in one go using checkboxes
- **Smart grouping**: Automatically groups the same package from different managers
- **Real-time validation**: Verify package names before adding them
- **Export ready**: Sets are saved with OS compatibility and manager preferences for optimal installation
### Search for Packages
Search for packages across all available package managers:
```bash
# Search across all managers
blacksmith search docker
# Search in a specific package manager (supports aliases)
blacksmith search git --manager winget
blacksmith search git --manager choco # Alias for chocolatey
# Limit results
blacksmith search python --limit 5
```
**Features:**
- **Real-time results**: Queries each package manager directly for up-to-date results
- **Manager aliases**: Use `choco` for `chocolatey`, `dnf` for `yum`, etc.
- **OS-aware errors**: Clear messages when requesting OS-specific managers (e.g., `apt` on Windows)
- **Unified display**: Results grouped by manager with descriptions
This is especially useful when creating custom sets, as it ensures you use the correct package names for each package manager.
### View Set Information
Get detailed information about a set, including OS compatibility and manager preferences:
```bash
# View info about a pre-made set
blacksmith info development
blacksmith info cybersecurity
# View info about a custom config file
blacksmith info --file path/to/config.yaml
```
### Export Sets
Export sets to native package manager formats for use outside of Blacksmith:
```bash
# Export to Winget JSON format
blacksmith export development --format winget
# Export to Chocolatey packages.config
blacksmith export development --format chocolatey
# Export to Apt text list
blacksmith export development --format apt
# Export with custom output file
blacksmith export development --format winget --output my-packages.json
```
**Supported formats:**
- `winget` - JSON array of package IDs
- `chocolatey` / `choco` - XML packages.config format
- `apt` - Plain text list
- `pacman` - Plain text list
- `scoop` - JSON array
### Validate Configuration Files
```bash
blacksmith validate path/to/config.yaml
```
### Installation Options
```bash
# Skip already installed packages
blacksmith install development --skip-installed
# Prefer a specific package manager (overrides set preferences)
blacksmith install development --prefer winget
# Force installation even if OS doesn't match set's target_os
blacksmith install development --force
```
### Uninstall Blacksmith
```bash
# Using the CLI (removes package and virtual environment)
blacksmith uninstall
# Skip confirmation prompt
blacksmith uninstall --yes
```
The uninstall command will:
- Remove Blacksmith from your Python environment
- Remove the virtual environment (if installed via `venv` method)
- Clean up the `blacksmith` command executable
## 📝 Configuration Format
Blacksmith uses YAML configuration files with support for cross-platform sets. Here's an example:
### Basic Format (Backward Compatible)
```yaml
name: "My Custom Set"
description: "My favorite development tools"
packages:
- name: git
managers:
apt: git
pacman: git
winget: Git.Git
chocolatey: git
scoop: git
- name: docker
managers:
apt: docker.io
pacman: docker
yum: docker
winget: Docker.DockerDesktop
```
### Advanced Format (Cross-Platform)
```yaml
name: "Cross-Platform Dev Tools"
description: "Development tools for Windows and Linux"
target_os: ["windows", "linux"] # OS compatibility
preferred_managers: # Manager preferences per OS
windows: ["winget", "chocolatey"]
linux: ["apt", "flatpak"]
managers_supported: # Limit to specific managers
- winget
- chocolatey
- apt
- flatpak
packages:
- name: git
managers:
winget: Git.Git
chocolatey: git
apt: git
flatpak: org.gnome.gitg
```
**Configuration Fields:**
- `name` (required) - Set name
- `description` (optional) - Set description
- `target_os` (optional) - List of target OSes: `["windows"]`, `["linux"]`, or `["windows", "linux"]`
- `preferred_managers` (optional) - Dictionary mapping OS to preferred manager order
- `managers_supported` (optional) - List of managers to limit installation to
- `packages` (required) - List of packages with manager-specific IDs
## 📦 Supported Package Managers
### Linux
- **apt** - Debian/Ubuntu
- **yum/dnf** - RHEL/Fedora
- **pacman** - Arch Linux
- **snap** - Universal Linux packages
- **flatpak** - Application sandboxing
### Windows
- **winget** - Windows Package Manager
- **chocolatey** - Windows package manager
- **scoop** - Command-line installer
**Smart Manager Selection:**
Blacksmith automatically detects which package managers are available on your system and uses intelligent selection:
- **Preference-based**: Uses `preferred_managers` from the set configuration if specified
- **OS-specific defaults**: Falls back to sensible defaults (e.g., `winget` > `chocolatey` > `scoop` on Windows)
- **Fallback logic**: If preferred manager isn't available, tries the next one in order
- **OS compatibility**: Checks if the set is compatible with your OS (can be overridden with `--force`)
- **Manager filtering**: Respects `managers_supported` to limit which managers are considered
## 🍎 macOS Support (Future)
macOS support is planned for a future release. While the codebase includes some macOS compatibility (OS detection, install scripts), full support is not yet available.
**Planned features for macOS:**
- Homebrew package manager integration
- MacPorts support (optional)
- Native macOS package installation workflows
- Full compatibility with macOS-specific tool installations
If you're interested in contributing macOS support, please check out our [Contributing](#-contributing) section or open an issue to discuss!
## 🎨 Pre-made Sets
### Development
Essential development tools including Git, Docker, VS Code, Python, Node.js, and more.
### Cybersecurity
Security and penetration testing tools including Nmap, Wireshark, Metasploit, Burp Suite, and more.
### Minimal
Lightweight setup with just the essentials: Git, curl, and Vim.
## 🛠️ Development
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/jimididit/blacksmith.git
cd blacksmith
# Create a virtual environment
python -m venv venv
# Activate it
# On Linux/Mac:
source venv/bin/activate
# On Windows:
venv\Scripts\activate
# Install in development mode
pip install -e .
# Install development dependencies (for testing and code quality)
pip install pytest pytest-cov pytest-mock ruff black mypy yamllint
```
### Project Structure
```
blacksmith/
├── blacksmith/
│ ├── cli.py # Main CLI interface
│ ├── config/ # Configuration system
│ │ ├── loader.py # Config file loading
│ │ ├── parser.py # YAML parsing
│ │ ├── preferences.py # Manager preference system
│ │ └── validator.py # Config validation
│ ├── export/ # Export functionality
│ │ ├── base.py # Base exporter class
│ │ ├── winget.py # Winget JSON exporter
│ │ ├── chocolatey.py # Chocolatey XML exporter
│ │ ├── apt.py # Apt list exporter
│ │ ├── pacman.py # Pacman list exporter
│ │ └── scoop.py # Scoop JSON exporter
│ ├── package_managers/ # Package manager implementations
│ ├── sets/ # Pre-made tool sets
│ └── utils/ # Utility modules
│ ├── os_detector.py # OS detection
│ └── ui.py # UI helpers (Rich)
├── tests/ # Test suite
├── scripts/ # Helper scripts
│ └── bump_version.py # Version bumping script
└── README.md
```
### Version Management
Blacksmith uses [Semantic Versioning](https://semver.org/) (SemVer): `MAJOR.MINOR.PATCH`
- **PATCH** (0.1.0 → 0.1.1): Bug fixes, security patches
- **MINOR** (0.1.0 → 0.2.0): New features (backward compatible)
- **MAJOR** (0.2.0 → 1.0.0): Breaking changes, first stable release
**Quick version bump:**
```bash
# Bump patch version (0.1.0 -> 0.1.1)
python scripts/bump_version.py --patch
# Bump minor version (0.1.0 -> 0.2.0)
python scripts/bump_version.py --minor
# Bump major version (0.1.0 -> 1.0.0)
python scripts/bump_version.py --major
# Or set a specific version
python scripts/bump_version.py 0.1.1
```
**Manual version update:**
Update the version in both `pyproject.toml` and `blacksmith/__init__.py`, then:
```bash
git tag -a v0.1.1 -m "Release version 0.1.1"
git push origin v0.1.1
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
### Getting Started
1. Fork the repository
2. Clone your fork: `git clone https://github.com/your-username/blacksmith.git`
3. Create a feature branch: `git checkout -b feature/AmazingFeature`
4. Set up your development environment (see the [Development](#️-development) section above)
### Development Workflow
1. Make your changes
2. Run tests locally (see [Testing](#testing) below)
3. Ensure code quality checks pass (see [Code Quality](#code-quality) below)
4. Commit your changes: `git commit -m 'Add some AmazingFeature'`
5. Push to your fork: `git push origin feature/AmazingFeature`
6. Open a Pull Request
### Testing
Before submitting a PR, please ensure all tests pass:
```bash
# Install test dependencies
pip install pytest pytest-cov pytest-mock
# Run all tests
pytest tests/ -v
# Run with coverage
pytest tests/ -v --cov=blacksmith --cov-report=term
# Run specific test file
pytest tests/test_cli.py -v
```
### Code Quality
We use several tools to maintain code quality. Please ensure your code passes these checks:
```bash
# Install development dependencies
pip install ruff black mypy yamllint
# Linting (check for errors)
ruff check blacksmith/
# Formatting (check if code is formatted)
ruff format --check blacksmith/
# Auto-fix linting issues
ruff check --fix blacksmith/
# Auto-format code
ruff format blacksmith/
# Type checking
mypy blacksmith/ --ignore-missing-imports
# YAML linting
yamllint blacksmith/sets/*.yaml
```
### Adding New Package Managers
To add support for a new package manager:
1. Create a new file in `blacksmith/package_managers/` (e.g., `brew.py`)
2. Inherit from `PackageManager` base class in `blacksmith/package_managers/base.py`
3. Implement required methods:
- `is_available()` - Check if the package manager is installed
- `install(packages)` - Install packages
- `is_installed(package)` - Check if a package is installed
- `search(query)` - Search for packages
- `update_package(package)` - Update a single package (optional but recommended)
4. Register it in `blacksmith/package_managers/detector.py`
5. Add it to the default preferences in `blacksmith/config/preferences.py` if applicable
6. Add tests in `tests/test_package_managers.py`
### Adding New Tool Sets
To add a new pre-made tool set:
1. Create a new YAML file in `blacksmith/sets/` (e.g., `gaming.yaml`)
2. Follow the existing format (see `blacksmith/sets/development.yaml` for reference)
3. Include package names for all supported package managers
4. Optionally add cross-platform fields:
- `target_os` - List of target OSes (e.g., `["windows", "linux"]`)
- `preferred_managers` - OS-specific manager preferences
- `managers_supported` - Limit to specific managers
5. Ensure YAML syntax is valid: `yamllint blacksmith/sets/gaming.yaml`
6. Test loading the set: `blacksmith list` should show your new set
7. Test the `info` command: `blacksmith info gaming` should display correctly
### Reporting Bugs
When reporting bugs, please include:
- Operating system and version
- Python version
- Blacksmith version (`blacksmith --version`)
- Steps to reproduce
- Expected vs actual behavior
- Error messages or logs (if applicable)
### Feature Requests
For feature requests, please:
- Open an issue describing the feature
- Explain the use case and benefits
- Discuss implementation approach (if you have ideas)
- Consider contributing the feature yourself!
### Code Style Guidelines
- Follow PEP 8 style guide
- Use type hints where possible
- Write docstrings for all functions and classes
- Keep functions focused and small
- Add comments for complex logic
- Use meaningful variable and function names
## 🔧 Troubleshooting Installation
### Command Not Found After Installation
If `blacksmith` is not recognized after installation, it's likely a PATH issue:
**Linux/macOS (with `--user` install):**
```bash
# Add to your ~/.bashrc, ~/.zshrc, or ~/.profile:
export PATH="$HOME/.local/bin:$PATH"
# Then reload your shell:
source ~/.bashrc # or source ~/.zshrc
```
**Windows (with `--user` install):**
```powershell
# Find your user Scripts directory:
python -m site --user-base
# Add it to PATH (replace with your actual path):
# Typically: %USERPROFILE%\AppData\Roaming\Python\Python3X\Scripts
# Or: %LOCALAPPDATA%\Programs\Python\Python3X\Scripts
# Then restart your terminal
```
**Use a Virtual Environment (Recommended)**
Using a virtual environment is the most reliable option and avoids PATH issues:
```bash
# Create and activate a virtual environment
python3 -m venv ~/.blacksmith-venv
# Activate it:
# Linux/macOS:
source ~/.blacksmith-venv/bin/activate
# Windows (PowerShell):
$env:USERPROFILE\.blacksmith-venv\Scripts\Activate.ps1
# Windows (CMD):
%USERPROFILE%\.blacksmith-venv\Scripts\activate.bat
# Install blacksmith
pip install jdi-blacksmith
# Now blacksmith will work as long as the venv is activated
blacksmith --version
```
### Permission Errors (Global Installation)
If you get permission errors when installing globally:
**Linux/macOS:**
```bash
# Use sudo (not recommended for security):
sudo pip install jdi-blacksmith
# Better: Use --user flag (no sudo needed):
pip install --user jdi-blacksmith
```
**Windows:**
```powershell
# Run PowerShell as Administrator, then:
pip install jdi-blacksmith
# Better: Use --user flag (no admin needed):
pip install --user jdi-blacksmith
```
### Installation Works But Command Not Found
If installation succeeds but the command isn't found:
1. **Check if it's installed:**
```bash
python -m blacksmith --version
```
2. **Find where pip installed the script:**
```bash
# Linux/macOS:
python -m site --user-base
# Then check: /bin/blacksmith
# Windows:
python -m site --user-base
# Then check: \Scripts\blacksmith.exe
```
3. **Verify the entry point:**
```bash
pip show jdi-blacksmith
# Look for "Location:" and "Entry-points:"
```
## 📄 License
This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.
## 👤 Author
**jimididit**
- GitHub: [@jimididit](https://github.com/jimididit)
- Instagram: [@jimididit](https://instagram.com/jimi.did.it)
- YouTube: [@jimididit](https://youtube.com/@jimididit)
- TikTok: [@jimididit](https://tiktok.com/@jimi.did.it)
- Website: [www.jimididit.com](https://jimididit.com)
- Discord: [NØKTURNAL COMMUNITY](https://jimididit.com/discord)
## 🙏 Acknowledgments
- Built with [Click](https://click.palletsprojects.com/) for CLI framework
- Beautiful terminal output powered by [Rich](https://github.com/Textualize/rich)
- Interactive prompts with [Questionary](https://github.com/tmbo/questionary)
## 📚 Additional Resources
- **Repository**: [https://github.com/jimididit/blacksmith](https://github.com/jimididit/blacksmith)
- [Issue Tracker](https://github.com/jimididit/blacksmith/issues)
- [Discussions](https://github.com/jimididit/blacksmith/discussions)
---
⭐ If you find this project helpful, please consider giving it a star on [GitHub](https://github.com/jimididit/blacksmith)!