{"id":36965412,"url":"https://github.com/jimididit/blacksmith","last_synced_at":"2026-01-13T19:59:04.469Z","repository":{"id":329059444,"uuid":"1115947295","full_name":"jimididit/blacksmith","owner":"jimididit","description":"A cross-platform CLI tool that automates the installation of development and cybersecurity toolsets after a fresh OS install.","archived":false,"fork":false,"pushed_at":"2025-12-17T04:38:15.000Z","size":228,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-20T17:32:08.759Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jimididit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-13T21:58:05.000Z","updated_at":"2025-12-17T04:38:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jimididit/blacksmith","commit_stats":null,"previous_names":["jimididit/blacksmith"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/jimididit/blacksmith","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimididit%2Fblacksmith","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimididit%2Fblacksmith/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimididit%2Fblacksmith/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimididit%2Fblacksmith/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jimididit","download_url":"https://codeload.github.com/jimididit/blacksmith/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimididit%2Fblacksmith/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28398633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apt","automation","chocolatey","cli","cross-platform","cybersecurity","development-tools","devops","fresh-install","linux","package-manager","productivity","provisioning","python","setup-automation","system-administration","windows","winget"],"created_at":"2026-01-13T19:59:03.619Z","updated_at":"2026-01-13T19:59:04.460Z","avatar_url":"https://github.com/jimididit.png","language":"Python","readme":"# Blacksmith 🔨\n\n\u003e A cross-platform CLI tool that automates the installation of development and cybersecurity tools after a fresh OS install.\n\n[![CI/CD Pipeline](https://github.com/jimididit/blacksmith/actions/workflows/ci.yml/badge.svg)](https://github.com/jimididit/blacksmith/actions/workflows/ci.yml)\n[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![Version](https://img.shields.io/badge/version-0.2.3-blue.svg)](https://github.com/jimididit/blacksmith/releases)\n[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)\n[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20Windows-lightgrey.svg)](https://github.com/jimididit/blacksmith)\n[![GitHub](https://img.shields.io/badge/GitHub-jimididit%2Fblacksmith-blue.svg)](https://github.com/jimididit/blacksmith)\n\n## ✨ Features\n\n- 🎯 **Pre-made tool sets** - Choose from curated sets of development or cybersecurity tools\n- 🛠️ **Custom configurations** - Create your own sets or use custom config files\n- 🔍 **Unified package search** - Search across all selected managers simultaneously with multi-select support\n- 🌐 **Cross-platform sets** - Define sets that work on Windows, Linux, or both with OS-specific manager preferences\n- 📦 **Multiple package managers** - Supports apt, yum, pacman, winget, chocolatey, scoop, snap, and flatpak\n- 🎯 **Smart manager selection** - Automatically uses preferred package managers with intelligent fallback\n- ✨ **Beautiful CLI** - Clean, intuitive interface with progress indicators and helpful feedback\n- 🎨 **Custom color scheme** - Elegant purple and cyan theme\n- ⚡ **Fast installation** - Automatically detects and uses the best package manager for each tool\n- ✅ **Package validation** - Verify package names before installation\n- 📤 **Export functionality** - Export sets to native package manager formats (Winget JSON, Chocolatey XML, etc.)\n- 🔄 **Update support** - Check for installed packages and update them when available\n- 📊 **Set information** - View detailed information about sets including OS compatibility and manager preferences\n\n## 📋 Prerequisites\n\n- Python 3.8 or higher\n- One or more supported package managers installed on your system\n\n## 🚀 Quick Start\n\n### Recommended: Install in a Virtual Environment\n\nWe recommend installing Blacksmith in a virtual environment to avoid PATH issues and ensure proper isolation.\n\n**1. Create a virtual environment:**\n\n**Linux/macOS:**\n\n```bash\npython3 -m venv ~/.blacksmith-venv\nsource ~/.blacksmith-venv/bin/activate\n```\n\n**Windows (PowerShell):**\n\n```powershell\npython -m venv $env:USERPROFILE\\.blacksmith-venv\n$env:USERPROFILE\\.blacksmith-venv\\Scripts\\Activate.ps1\n```\n\n**Windows (CMD):**\n\n```cmd\npython -m venv %USERPROFILE%\\.blacksmith-venv\n%USERPROFILE%\\.blacksmith-venv\\Scripts\\activate.bat\n```\n\n**2. Install Blacksmith:**\n\n**Option A: Install from PyPI (recommended)**\n\n```bash\npip install jdi-blacksmith\n```\n\n**Option B: Install from source**\n\n```bash\ngit clone https://github.com/jimididit/blacksmith.git\ncd blacksmith\npip install -e .\n```\n\n**3. Verify installation:**\n\n```bash\nblacksmith --version\n```\n\n**4. Using Blacksmith:**\n\nAfter installation, make sure your virtual environment is activated. To activate it again later:\n\n**Linux/macOS:**\n\n```bash\nsource ~/.blacksmith-venv/bin/activate\n```\n\n**Windows (PowerShell):**\n\n```powershell\n$env:USERPROFILE\\.blacksmith-venv\\Scripts\\Activate.ps1\n```\n\n**Windows (CMD):**\n\n```cmd\n%USERPROFILE%\\.blacksmith-venv\\Scripts\\activate.bat\n```\n\n**Optional:** Create an alias for easier access:\n\n**Linux/macOS (~/.bashrc or ~/.zshrc):**\n\n```bash\nalias blacksmith=\"$HOME/.blacksmith-venv/bin/blacksmith\"\n```\n\n**Windows (PowerShell Profile):**\n\n```powershell\nSet-Alias blacksmith \"$env:USERPROFILE\\.blacksmith-venv\\Scripts\\blacksmith.exe\"\n```\n\n### Alternative: Install Without Virtual Environment\n\nIf you prefer not to use a virtual environment, you can install directly:\n\n```bash\n# From PyPI\npip install jdi-blacksmith\n\n# Or from source\ngit clone https://github.com/jimididit/blacksmith.git\ncd blacksmith\npip install -e .\n```\n\n\u003e ⚠️ **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.\n\n\u003e 💡 **Having installation issues?** See the [Troubleshooting Installation](#-troubleshooting-installation) section below.\n\n## 📖 Usage\n\n### Quick Command Reference\n\n```bash\n# Interactive mode (shows menu)\nblacksmith\n\n# List available sets with OS compatibility\nblacksmith list\n\n# View detailed set information\nblacksmith info \u003cset_name\u003e\n\n# Install a set\nblacksmith install \u003cset_name\u003e\n\n# Create a custom set\nblacksmith create\n\n# Search for packages\nblacksmith search \u003cquery\u003e [--manager \u003cname\u003e]\n\n# Export set to native format\nblacksmith export \u003cset_name\u003e --format \u003cformat\u003e\n\n# Validate a config file\nblacksmith validate \u003cpath\u003e\n\n# Uninstall Blacksmith\nblacksmith uninstall\n```\n\n### Interactive Mode\n\nThe easiest way to use Blacksmith is through the interactive menu:\n\n```bash\nblacksmith\n```\n\nThis will display a beautiful banner and an interactive menu to select and install tool sets.\n\n### List Available Sets\n\nView all available sets with OS compatibility indicators:\n\n```bash\nblacksmith list\n```\n\nThe list shows:\n\n- Set name and description\n- OS compatibility badges (🪟 Windows, 🐧 Linux, 🍎 macOS)\n- Preferred package managers\n- Package count\n- Compatibility status with your current OS\n\n### Install Pre-made Sets\n\n```bash\n# List available sets\nblacksmith list\n\n# Install a specific set\nblacksmith install development\nblacksmith install cybersecurity\nblacksmith install minimal\n```\n\n### Install from Custom Config\n\n```bash\nblacksmith install --file path/to/your-config.yaml\n```\n\n### Create Your Own Set\n\n```bash\n# Standard mode (cross-platform, multi-manager)\nblacksmith create\n\n# Advanced mode (single-OS, single-manager sets)\nblacksmith create --advanced\n```\n\nThis launches an interactive wizard to create a custom tool set configuration. The wizard includes:\n\n- **OS selection**: Choose Windows, Linux, or both for cross-platform sets\n- **Manager selection**: Select which package managers to target for each OS\n- **Unified search**: Search across all selected managers simultaneously - see results from all managers at once\n- **Multi-select**: Select packages from multiple managers in one go using checkboxes\n- **Smart grouping**: Automatically groups the same package from different managers\n- **Real-time validation**: Verify package names before adding them\n- **Export ready**: Sets are saved with OS compatibility and manager preferences for optimal installation\n\n### Search for Packages\n\nSearch for packages across all available package managers:\n\n```bash\n# Search across all managers\nblacksmith search docker\n\n# Search in a specific package manager (supports aliases)\nblacksmith search git --manager winget\nblacksmith search git --manager choco    # Alias for chocolatey\n\n# Limit results\nblacksmith search python --limit 5\n```\n\n**Features:**\n\n- **Real-time results**: Queries each package manager directly for up-to-date results\n- **Manager aliases**: Use `choco` for `chocolatey`, `dnf` for `yum`, etc.\n- **OS-aware errors**: Clear messages when requesting OS-specific managers (e.g., `apt` on Windows)\n- **Unified display**: Results grouped by manager with descriptions\n\nThis is especially useful when creating custom sets, as it ensures you use the correct package names for each package manager.\n\n### View Set Information\n\nGet detailed information about a set, including OS compatibility and manager preferences:\n\n```bash\n# View info about a pre-made set\nblacksmith info development\nblacksmith info cybersecurity\n\n# View info about a custom config file\nblacksmith info --file path/to/config.yaml\n```\n\n### Export Sets\n\nExport sets to native package manager formats for use outside of Blacksmith:\n\n```bash\n# Export to Winget JSON format\nblacksmith export development --format winget\n\n# Export to Chocolatey packages.config\nblacksmith export development --format chocolatey\n\n# Export to Apt text list\nblacksmith export development --format apt\n\n# Export with custom output file\nblacksmith export development --format winget --output my-packages.json\n```\n\n**Supported formats:**\n\n- `winget` - JSON array of package IDs\n- `chocolatey` / `choco` - XML packages.config format\n- `apt` - Plain text list\n- `pacman` - Plain text list\n- `scoop` - JSON array\n\n### Validate Configuration Files\n\n```bash\nblacksmith validate path/to/config.yaml\n```\n\n### Installation Options\n\n```bash\n# Skip already installed packages\nblacksmith install development --skip-installed\n\n# Prefer a specific package manager (overrides set preferences)\nblacksmith install development --prefer winget\n\n# Force installation even if OS doesn't match set's target_os\nblacksmith install development --force\n```\n\n### Uninstall Blacksmith\n\n```bash\n# Using the CLI (removes package and virtual environment)\nblacksmith uninstall\n\n# Skip confirmation prompt\nblacksmith uninstall --yes\n```\n\nThe uninstall command will:\n\n- Remove Blacksmith from your Python environment\n- Remove the virtual environment (if installed via `venv` method)\n- Clean up the `blacksmith` command executable\n\n## 📝 Configuration Format\n\nBlacksmith uses YAML configuration files with support for cross-platform sets. Here's an example:\n\n### Basic Format (Backward Compatible)\n\n```yaml\nname: \"My Custom Set\"\ndescription: \"My favorite development tools\"\npackages:\n  - name: git\n    managers:\n      apt: git\n      pacman: git\n      winget: Git.Git\n      chocolatey: git\n      scoop: git\n  \n  - name: docker\n    managers:\n      apt: docker.io\n      pacman: docker\n      yum: docker\n      winget: Docker.DockerDesktop\n```\n\n### Advanced Format (Cross-Platform)\n\n```yaml\nname: \"Cross-Platform Dev Tools\"\ndescription: \"Development tools for Windows and Linux\"\ntarget_os: [\"windows\", \"linux\"]  # OS compatibility\npreferred_managers:              # Manager preferences per OS\n  windows: [\"winget\", \"chocolatey\"]\n  linux: [\"apt\", \"flatpak\"]\nmanagers_supported:              # Limit to specific managers\n  - winget\n  - chocolatey\n  - apt\n  - flatpak\npackages:\n  - name: git\n    managers:\n      winget: Git.Git\n      chocolatey: git\n      apt: git\n      flatpak: org.gnome.gitg\n```\n\n**Configuration Fields:**\n\n- `name` (required) - Set name\n- `description` (optional) - Set description\n- `target_os` (optional) - List of target OSes: `[\"windows\"]`, `[\"linux\"]`, or `[\"windows\", \"linux\"]`\n- `preferred_managers` (optional) - Dictionary mapping OS to preferred manager order\n- `managers_supported` (optional) - List of managers to limit installation to\n- `packages` (required) - List of packages with manager-specific IDs\n\n## 📦 Supported Package Managers\n\n### Linux\n\n- **apt** - Debian/Ubuntu\n- **yum/dnf** - RHEL/Fedora\n- **pacman** - Arch Linux\n- **snap** - Universal Linux packages\n- **flatpak** - Application sandboxing\n\n### Windows\n\n- **winget** - Windows Package Manager\n- **chocolatey** - Windows package manager\n- **scoop** - Command-line installer\n\n**Smart Manager Selection:**\n\nBlacksmith automatically detects which package managers are available on your system and uses intelligent selection:\n\n- **Preference-based**: Uses `preferred_managers` from the set configuration if specified\n- **OS-specific defaults**: Falls back to sensible defaults (e.g., `winget` \u003e `chocolatey` \u003e `scoop` on Windows)\n- **Fallback logic**: If preferred manager isn't available, tries the next one in order\n- **OS compatibility**: Checks if the set is compatible with your OS (can be overridden with `--force`)\n- **Manager filtering**: Respects `managers_supported` to limit which managers are considered\n\n## 🍎 macOS Support (Future)\n\nmacOS support is planned for a future release. While the codebase includes some macOS compatibility (OS detection, install scripts), full support is not yet available.\n\n**Planned features for macOS:**\n\n- Homebrew package manager integration\n- MacPorts support (optional)\n- Native macOS package installation workflows\n- Full compatibility with macOS-specific tool installations\n\nIf you're interested in contributing macOS support, please check out our [Contributing](#-contributing) section or open an issue to discuss!\n\n## 🎨 Pre-made Sets\n\n### Development\n\nEssential development tools including Git, Docker, VS Code, Python, Node.js, and more.\n\n### Cybersecurity\n\nSecurity and penetration testing tools including Nmap, Wireshark, Metasploit, Burp Suite, and more.\n\n### Minimal\n\nLightweight setup with just the essentials: Git, curl, and Vim.\n\n## 🛠️ Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/jimididit/blacksmith.git\ncd blacksmith\n\n# Create a virtual environment\npython -m venv venv\n\n# Activate it\n# On Linux/Mac:\nsource venv/bin/activate\n# On Windows:\nvenv\\Scripts\\activate\n\n# Install in development mode\npip install -e .\n\n# Install development dependencies (for testing and code quality)\npip install pytest pytest-cov pytest-mock ruff black mypy yamllint\n```\n\n### Project Structure\n\n```\nblacksmith/\n├── blacksmith/\n│   ├── cli.py              # Main CLI interface\n│   ├── config/             # Configuration system\n│   │   ├── loader.py       # Config file loading\n│   │   ├── parser.py       # YAML parsing\n│   │   ├── preferences.py  # Manager preference system\n│   │   └── validator.py    # Config validation\n│   ├── export/             # Export functionality\n│   │   ├── base.py         # Base exporter class\n│   │   ├── winget.py       # Winget JSON exporter\n│   │   ├── chocolatey.py   # Chocolatey XML exporter\n│   │   ├── apt.py          # Apt list exporter\n│   │   ├── pacman.py       # Pacman list exporter\n│   │   └── scoop.py        # Scoop JSON exporter\n│   ├── package_managers/   # Package manager implementations\n│   ├── sets/               # Pre-made tool sets\n│   └── utils/              # Utility modules\n│       ├── os_detector.py  # OS detection\n│       └── ui.py           # UI helpers (Rich)\n├── tests/                  # Test suite\n├── scripts/                # Helper scripts\n│   └── bump_version.py     # Version bumping script\n└── README.md\n```\n\n### Version Management\n\nBlacksmith uses [Semantic Versioning](https://semver.org/) (SemVer): `MAJOR.MINOR.PATCH`\n\n- **PATCH** (0.1.0 → 0.1.1): Bug fixes, security patches\n- **MINOR** (0.1.0 → 0.2.0): New features (backward compatible)\n- **MAJOR** (0.2.0 → 1.0.0): Breaking changes, first stable release\n\n**Quick version bump:**\n\n```bash\n# Bump patch version (0.1.0 -\u003e 0.1.1)\npython scripts/bump_version.py --patch\n\n# Bump minor version (0.1.0 -\u003e 0.2.0)\npython scripts/bump_version.py --minor\n\n# Bump major version (0.1.0 -\u003e 1.0.0)\npython scripts/bump_version.py --major\n\n# Or set a specific version\npython scripts/bump_version.py 0.1.1\n```\n\n**Manual version update:**\nUpdate the version in both `pyproject.toml` and `blacksmith/__init__.py`, then:\n\n```bash\ngit tag -a v0.1.1 -m \"Release version 0.1.1\"\ngit push origin v0.1.1\n```\n\n## 🤝 Contributing\n\nContributions 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.\n\n### Getting Started\n\n1. Fork the repository\n2. Clone your fork: `git clone https://github.com/your-username/blacksmith.git`\n3. Create a feature branch: `git checkout -b feature/AmazingFeature`\n4. Set up your development environment (see the [Development](#️-development) section above)\n\n### Development Workflow\n\n1. Make your changes\n2. Run tests locally (see [Testing](#testing) below)\n3. Ensure code quality checks pass (see [Code Quality](#code-quality) below)\n4. Commit your changes: `git commit -m 'Add some AmazingFeature'`\n5. Push to your fork: `git push origin feature/AmazingFeature`\n6. Open a Pull Request\n\n### Testing\n\nBefore submitting a PR, please ensure all tests pass:\n\n```bash\n# Install test dependencies\npip install pytest pytest-cov pytest-mock\n\n# Run all tests\npytest tests/ -v\n\n# Run with coverage\npytest tests/ -v --cov=blacksmith --cov-report=term\n\n# Run specific test file\npytest tests/test_cli.py -v\n```\n\n### Code Quality\n\nWe use several tools to maintain code quality. Please ensure your code passes these checks:\n\n```bash\n# Install development dependencies\npip install ruff black mypy yamllint\n\n# Linting (check for errors)\nruff check blacksmith/\n\n# Formatting (check if code is formatted)\nruff format --check blacksmith/\n\n# Auto-fix linting issues\nruff check --fix blacksmith/\n\n# Auto-format code\nruff format blacksmith/\n\n# Type checking\nmypy blacksmith/ --ignore-missing-imports\n\n# YAML linting\nyamllint blacksmith/sets/*.yaml\n```\n\n### Adding New Package Managers\n\nTo add support for a new package manager:\n\n1. Create a new file in `blacksmith/package_managers/` (e.g., `brew.py`)\n2. Inherit from `PackageManager` base class in `blacksmith/package_managers/base.py`\n3. Implement required methods:\n   - `is_available()` - Check if the package manager is installed\n   - `install(packages)` - Install packages\n   - `is_installed(package)` - Check if a package is installed\n   - `search(query)` - Search for packages\n   - `update_package(package)` - Update a single package (optional but recommended)\n4. Register it in `blacksmith/package_managers/detector.py`\n5. Add it to the default preferences in `blacksmith/config/preferences.py` if applicable\n6. Add tests in `tests/test_package_managers.py`\n\n### Adding New Tool Sets\n\nTo add a new pre-made tool set:\n\n1. Create a new YAML file in `blacksmith/sets/` (e.g., `gaming.yaml`)\n2. Follow the existing format (see `blacksmith/sets/development.yaml` for reference)\n3. Include package names for all supported package managers\n4. Optionally add cross-platform fields:\n   - `target_os` - List of target OSes (e.g., `[\"windows\", \"linux\"]`)\n   - `preferred_managers` - OS-specific manager preferences\n   - `managers_supported` - Limit to specific managers\n5. Ensure YAML syntax is valid: `yamllint blacksmith/sets/gaming.yaml`\n6. Test loading the set: `blacksmith list` should show your new set\n7. Test the `info` command: `blacksmith info gaming` should display correctly\n\n### Reporting Bugs\n\nWhen reporting bugs, please include:\n\n- Operating system and version\n- Python version\n- Blacksmith version (`blacksmith --version`)\n- Steps to reproduce\n- Expected vs actual behavior\n- Error messages or logs (if applicable)\n\n### Feature Requests\n\nFor feature requests, please:\n\n- Open an issue describing the feature\n- Explain the use case and benefits\n- Discuss implementation approach (if you have ideas)\n- Consider contributing the feature yourself!\n\n### Code Style Guidelines\n\n- Follow PEP 8 style guide\n- Use type hints where possible\n- Write docstrings for all functions and classes\n- Keep functions focused and small\n- Add comments for complex logic\n- Use meaningful variable and function names\n\n## 🔧 Troubleshooting Installation\n\n### Command Not Found After Installation\n\nIf `blacksmith` is not recognized after installation, it's likely a PATH issue:\n\n**Linux/macOS (with `--user` install):**\n\n```bash\n# Add to your ~/.bashrc, ~/.zshrc, or ~/.profile:\nexport PATH=\"$HOME/.local/bin:$PATH\"\n\n# Then reload your shell:\nsource ~/.bashrc  # or source ~/.zshrc\n```\n\n**Windows (with `--user` install):**\n\n```powershell\n# Find your user Scripts directory:\npython -m site --user-base\n\n# Add it to PATH (replace with your actual path):\n# Typically: %USERPROFILE%\\AppData\\Roaming\\Python\\Python3X\\Scripts\n# Or: %LOCALAPPDATA%\\Programs\\Python\\Python3X\\Scripts\n\n# Then restart your terminal\n```\n\n**Use a Virtual Environment (Recommended)**\n\nUsing a virtual environment is the most reliable option and avoids PATH issues:\n\n```bash\n# Create and activate a virtual environment\npython3 -m venv ~/.blacksmith-venv\n\n# Activate it:\n# Linux/macOS:\nsource ~/.blacksmith-venv/bin/activate\n# Windows (PowerShell):\n$env:USERPROFILE\\.blacksmith-venv\\Scripts\\Activate.ps1\n# Windows (CMD):\n%USERPROFILE%\\.blacksmith-venv\\Scripts\\activate.bat\n\n# Install blacksmith\npip install jdi-blacksmith\n\n# Now blacksmith will work as long as the venv is activated\nblacksmith --version\n```\n\n### Permission Errors (Global Installation)\n\nIf you get permission errors when installing globally:\n\n**Linux/macOS:**\n\n```bash\n# Use sudo (not recommended for security):\nsudo pip install jdi-blacksmith\n\n# Better: Use --user flag (no sudo needed):\npip install --user jdi-blacksmith\n```\n\n**Windows:**\n\n```powershell\n# Run PowerShell as Administrator, then:\npip install jdi-blacksmith\n\n# Better: Use --user flag (no admin needed):\npip install --user jdi-blacksmith\n```\n\n### Installation Works But Command Not Found\n\nIf installation succeeds but the command isn't found:\n\n1. **Check if it's installed:**\n\n   ```bash\n   python -m blacksmith --version\n   ```\n\n2. **Find where pip installed the script:**\n\n   ```bash\n   # Linux/macOS:\n   python -m site --user-base\n   # Then check: \u003cpath\u003e/bin/blacksmith\n   \n   # Windows:\n   python -m site --user-base\n   # Then check: \u003cpath\u003e\\Scripts\\blacksmith.exe\n   ```\n\n3. **Verify the entry point:**\n\n   ```bash\n   pip show jdi-blacksmith\n   # Look for \"Location:\" and \"Entry-points:\"\n   ```\n\n## 📄 License\n\nThis project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.\n\n## 👤 Author\n\n**jimididit**\n\n- GitHub: [@jimididit](https://github.com/jimididit)\n- Instagram: [@jimididit](https://instagram.com/jimi.did.it)\n- YouTube: [@jimididit](https://youtube.com/@jimididit)\n- TikTok: [@jimididit](https://tiktok.com/@jimi.did.it)\n- Website: [www.jimididit.com](https://jimididit.com)\n- Discord: [NØKTURNAL COMMUNITY](https://jimididit.com/discord)\n\n## 🙏 Acknowledgments\n\n- Built with [Click](https://click.palletsprojects.com/) for CLI framework\n- Beautiful terminal output powered by [Rich](https://github.com/Textualize/rich)\n- Interactive prompts with [Questionary](https://github.com/tmbo/questionary)\n\n## 📚 Additional Resources\n\n- **Repository**: [https://github.com/jimididit/blacksmith](https://github.com/jimididit/blacksmith)\n- [Issue Tracker](https://github.com/jimididit/blacksmith/issues)\n- [Discussions](https://github.com/jimididit/blacksmith/discussions)\n\n---\n\n⭐ If you find this project helpful, please consider giving it a star on [GitHub](https://github.com/jimididit/blacksmith)!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimididit%2Fblacksmith","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjimididit%2Fblacksmith","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimididit%2Fblacksmith/lists"}