jdi-blacksmith
Advanced tools
A cross-platform CLI tool that automates the installation of development and cybersecurity tools after a fresh OS install.
We recommend installing Blacksmith in a virtual environment to avoid PATH issues and ensure proper isolation.
1. Create a virtual environment:
Linux/macOS:
python3 -m venv ~/.blacksmith-venv
source ~/.blacksmith-venv/bin/activate
Windows (PowerShell):
python -m venv $env:USERPROFILE\.blacksmith-venv
$env:USERPROFILE\.blacksmith-venv\Scripts\Activate.ps1
Windows (CMD):
python -m venv %USERPROFILE%\.blacksmith-venv
%USERPROFILE%\.blacksmith-venv\Scripts\activate.bat
2. Install Blacksmith:
Option A: Install from PyPI (recommended)
pip install jdi-blacksmith
Option B: Install from source
git clone https://github.com/jimididit/blacksmith.git
cd blacksmith
pip install -e .
3. Verify installation:
blacksmith --version
4. Using Blacksmith:
After installation, make sure your virtual environment is activated. To activate it again later:
Linux/macOS:
source ~/.blacksmith-venv/bin/activate
Windows (PowerShell):
$env:USERPROFILE\.blacksmith-venv\Scripts\Activate.ps1
Windows (CMD):
%USERPROFILE%\.blacksmith-venv\Scripts\activate.bat
Optional: Create an alias for easier access:
Linux/macOS (~/.bashrc or ~/.zshrc):
alias blacksmith="$HOME/.blacksmith-venv/bin/blacksmith"
Windows (PowerShell Profile):
Set-Alias blacksmith "$env:USERPROFILE\.blacksmith-venv\Scripts\blacksmith.exe"
If you prefer not to use a virtual environment, you can install directly:
# 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
blacksmithis not recognized after installation, you may need to add Python's Scripts/bin directory to your PATH. See the Troubleshooting Installation section below.
💡 Having installation issues? See the Troubleshooting Installation section below.
# Interactive mode (shows menu)
blacksmith
# List available sets with OS compatibility
blacksmith list
# View detailed set information
blacksmith info <set_name>
# Install a set
blacksmith install <set_name>
# Create a custom set
blacksmith create
# Search for packages
blacksmith search <query> [--manager <name>]
# Export set to native format
blacksmith export <set_name> --format <format>
# Validate a config file
blacksmith validate <path>
# Uninstall Blacksmith
blacksmith uninstall
The easiest way to use Blacksmith is through the interactive menu:
blacksmith
This will display a beautiful banner and an interactive menu to select and install tool sets.
View all available sets with OS compatibility indicators:
blacksmith list
The list shows:
# List available sets
blacksmith list
# Install a specific set
blacksmith install development
blacksmith install cybersecurity
blacksmith install minimal
blacksmith install --file path/to/your-config.yaml
# 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:
Search for packages across all available package managers:
# 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:
choco for chocolatey, dnf for yum, etc.apt on Windows)This is especially useful when creating custom sets, as it ensures you use the correct package names for each package manager.
Get detailed information about a set, including OS compatibility and manager preferences:
# 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 to native package manager formats for use outside of Blacksmith:
# 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 IDschocolatey / choco - XML packages.config formatapt - Plain text listpacman - Plain text listscoop - JSON arrayblacksmith validate path/to/config.yaml
# 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
# Using the CLI (removes package and virtual environment)
blacksmith uninstall
# Skip confirmation prompt
blacksmith uninstall --yes
The uninstall command will:
venv method)blacksmith command executableBlacksmith uses YAML configuration files with support for cross-platform sets. Here's an example:
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
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 namedescription (optional) - Set descriptiontarget_os (optional) - List of target OSes: ["windows"], ["linux"], or ["windows", "linux"]preferred_managers (optional) - Dictionary mapping OS to preferred manager ordermanagers_supported (optional) - List of managers to limit installation topackages (required) - List of packages with manager-specific IDsSmart Manager Selection:
Blacksmith automatically detects which package managers are available on your system and uses intelligent selection:
preferred_managers from the set configuration if specifiedwinget > chocolatey > scoop on Windows)--force)managers_supported to limit which managers are consideredmacOS 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:
If you're interested in contributing macOS support, please check out our Contributing section or open an issue to discuss!
Essential development tools including Git, Docker, VS Code, Python, Node.js, and more.
Security and penetration testing tools including Nmap, Wireshark, Metasploit, Burp Suite, and more.
Lightweight setup with just the essentials: Git, curl, and Vim.
# 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
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
Blacksmith uses Semantic Versioning (SemVer): MAJOR.MINOR.PATCH
Quick version bump:
# 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:
git tag -a v0.1.1 -m "Release version 0.1.1"
git push origin v0.1.1
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.
git clone https://github.com/your-username/blacksmith.gitgit checkout -b feature/AmazingFeaturegit commit -m 'Add some AmazingFeature'git push origin feature/AmazingFeatureBefore submitting a PR, please ensure all tests pass:
# 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
We use several tools to maintain code quality. Please ensure your code passes these checks:
# 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
To add support for a new package manager:
blacksmith/package_managers/ (e.g., brew.py)PackageManager base class in blacksmith/package_managers/base.pyis_available() - Check if the package manager is installedinstall(packages) - Install packagesis_installed(package) - Check if a package is installedsearch(query) - Search for packagesupdate_package(package) - Update a single package (optional but recommended)blacksmith/package_managers/detector.pyblacksmith/config/preferences.py if applicabletests/test_package_managers.pyTo add a new pre-made tool set:
blacksmith/sets/ (e.g., gaming.yaml)blacksmith/sets/development.yaml for reference)target_os - List of target OSes (e.g., ["windows", "linux"])preferred_managers - OS-specific manager preferencesmanagers_supported - Limit to specific managersyamllint blacksmith/sets/gaming.yamlblacksmith list should show your new setinfo command: blacksmith info gaming should display correctlyWhen reporting bugs, please include:
blacksmith --version)For feature requests, please:
If blacksmith is not recognized after installation, it's likely a PATH issue:
Linux/macOS (with --user install):
# 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):
# 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:
# 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
If you get permission errors when installing globally:
Linux/macOS:
# Use sudo (not recommended for security):
sudo pip install jdi-blacksmith
# Better: Use --user flag (no sudo needed):
pip install --user jdi-blacksmith
Windows:
# Run PowerShell as Administrator, then:
pip install jdi-blacksmith
# Better: Use --user flag (no admin needed):
pip install --user jdi-blacksmith
If installation succeeds but the command isn't found:
Check if it's installed:
python -m blacksmith --version
Find where pip installed the script:
# Linux/macOS:
python -m site --user-base
# Then check: <path>/bin/blacksmith
# Windows:
python -m site --user-base
# Then check: <path>\Scripts\blacksmith.exe
Verify the entry point:
pip show jdi-blacksmith
# Look for "Location:" and "Entry-points:"
This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
jimididit
⭐ If you find this project helpful, please consider giving it a star on GitHub!
FAQs
A cross-platform CLI tool for installing development and cybersecurity tools
We found that jdi-blacksmith demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.