{"id":29153675,"url":"https://github.com/mrsnakedoc/keg","last_synced_at":"2026-04-10T06:55:12.955Z","repository":{"id":301909214,"uuid":"1009175456","full_name":"MrSnakeDoc/keg","owner":"MrSnakeDoc","description":"A secure, modular, and self-updating CLI to bootstrap and manage your development environment.","archived":false,"fork":false,"pushed_at":"2025-08-03T04:19:24.000Z","size":98,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-03T04:22:26.959Z","etag":null,"topics":["automation","bootstrap","cli","golang","homebrew","linux","zsh"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MrSnakeDoc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-26T17:41:30.000Z","updated_at":"2025-08-03T03:10:27.000Z","dependencies_parsed_at":"2025-06-29T15:23:22.815Z","dependency_job_id":"98fb7e98-76ec-4bb1-ad48-c8c24cd1444e","html_url":"https://github.com/MrSnakeDoc/keg","commit_stats":null,"previous_names":["mrsnakedoc/keg"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/MrSnakeDoc/keg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrSnakeDoc%2Fkeg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrSnakeDoc%2Fkeg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrSnakeDoc%2Fkeg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrSnakeDoc%2Fkeg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MrSnakeDoc","download_url":"https://codeload.github.com/MrSnakeDoc/keg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrSnakeDoc%2Fkeg/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270099346,"owners_count":24527028,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["automation","bootstrap","cli","golang","homebrew","linux","zsh"],"created_at":"2025-07-01T02:01:44.338Z","updated_at":"2025-12-30T21:46:44.254Z","avatar_url":"https://github.com/MrSnakeDoc.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Go](https://img.shields.io/badge/go-1.24%2B-blue)\n![goreleaser](https://github.com/MrSnakeDoc/keg/actions/workflows/release.yml/badge.svg)\n![Go Report Card](https://goreportcard.com/badge/github.com/MrSnakeDoc/keg)\n![License](https://img.shields.io/badge/license-MIT-green)\n\n# Keg CLI\n\nA modern, opinionated CLI to automate and manage your Linux development environment with style.\nReproducible, idempotent, and fast.\n\n---\n\n## 💚 Shout-out to [Homebrew](https://brew.sh)\n\nKeg is built on top of the Homebrew ecosystem and uses it as its package management backend.  \nIf you enjoy using Keg, consider contributing to or supporting the Homebrew project — without their amazing work, Keg simply wouldn’t exist.\n\n## Why Keg Exists?\n\n- Reinstalling Linux machines over and over wastes time. Instead of another brittle Bash script, I wanted an idempotent, reproducible, portable CLI: one `keg deploy` and my dev environment is back on Ubuntu, Fedora, or Arch.\n- Keg does not replace Homebrew or Ansible; it’s a small, fast layer focused on developer experience—centralized config, a safe self-update path, and a clean, testable Go codebase.\n\n---\n\nTable of Contents\n- [Keg CLI](#keg-cli)\n  - [🚀 Features](#-features)\n  - [🖥️ Prerequisites](#️-prerequisites)\n  - [📦 Installation](#-installation)\n    - [From Bash Script](#from-bash-script)\n    - [From Source](#from-source)\n  - [⚙️ Configuration](#️-configuration)\n  - [🛠️ Usage](#️-usage)\n    - [Search packages](#search-packages)\n  - [🔄 Update Keg itself](#-update-keg-itself)\n  - [Global options](#global-options)\n  - [🧪 Testing \\\u0026 Development](#-testing--development)\n  - [📝 Roadmap](#-roadmap)\n  - [📄 License](#-license)\n  - [💡 Tips](#-tips)\n---\n\n## 🚀 Features\n\n- 🚀 ZSH auto-installation and configuration\n- 🍺 Homebrew auto-installation and management\n- 📋 Package management (install, upgrade, delete, list)\n- ⚡ Optional packages\n- 🗄️ Centralized config and state management\n- 🔄 Automatic self-update (via GitHub Releases, with SHA256 verification)\n- ❌ Robust error handling and clear user feedback\n- 🧪 Mockable runners and HTTP clients for easy testing\n\n---\n\n## 🖥️ Prerequisites\n\n- Linux (tested on Ubuntu, Fedora, Arch)\n- Go 1.24+ (to build from source)\n- Homebrew (auto-installed if missing)\n\n---\n\n## 📦 Installation\n\n### From Bash Script\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/MrSnakeDoc/keg/main/scripts/install.sh | bash -\n```\n\n * Security \u0026 integrity\n\n    - The installer fetches artifacts from official GitHub Releases only.\n    - Each release publishes checksums.txt (and optionally a signature).\n    - The script verifies the downloaded artifact against checksums.txt.\n    - No third-party mirrors and no telemetry.\n\n### From Source\n\n```bash\ngit clone https://github.com/MrSnakeDoc/keg.git\ncd keg\nmake build\n```\n\n---\n\n## ⚙️ Configuration\n\n- Run `keg init` to create a `keg.yml` in your current directory and initialize global config in `~/.config/keg`.\n- All package operations are based on this config file.\n- State and update info are stored in `~/.local/state/keg/update-check.json`.\n\nExample `keg.yml`:\n\n```yaml\npackages:\n  - command: eza\n  - command: bat\n  - command: lazygit\n    optional: true\n  - command: ripgrep\n    binary: rg\n    optional: true\n```\n\n---\n\n## 🛠️ Usage\n\n| Command                              | What it does                                               |\n| ------------------------------------ | ---------------------------------------------------------- |\n| `keg bootstrap`                      | Install ZSH if missing and set it as default               |\n| `keg deploy`                         | Install Homebrew if needed + all packages                  |\n| `keg install [pkgs...]`              | Install packages (default: all non-optional from manifest) |\n| `keg install --all`                  | Install all packages (including optional)                  |\n| `keg install foo --add`              | Install and add a package to `keg.yml`                     |\n| `keg install foo --add --optional`   | Install and add an optional package                        |\n| `keg install foo --add --binary bar` | Install and add a package with custom binary name          |\n| `keg list`                           | List packages and their status                             |\n| `keg upgrade [pkgs...]`              | Upgrade packages (default: all in manifest)                |\n| `keg upgrade --check` or `-c`        | Only check for available upgrades                          |\n| `keg upgrade --all`                  | Upgrade all packages (manifest + ad-hoc installed pkgs)    |\n| `keg delete [pkgs...]`               | Uninstall packages from the system                         |\n| `keg delete --all`                   | Uninstall all packages listed in manifest                  |\n| `keg delete foo --remove`            | Uninstall and remove package from manifest                 |\n| `keg delete --all --remove --force`  | Purge system + manifest (⚠ destructive)                    |\n| `keg --version`                      | Show CLI version                                           |\n| `keg --no-update-check`              | Skip update check (for scripting)                          |\n| `keg search \u003cquery\u003e [opts]`                 | Search packages in the Homebrew index (substring, exact, or regex) |\n\n\n### Search packages\n\n`keg search` lets you query the Homebrew index directly.\n\nExamples:\n\n```bash\nkeg search eza              # substring match\nkeg search eza --exact      # exact match\nkeg search '^rg' --regex    # regex match\nkeg search rip --no-desc    # hide description column\nkeg search rg --limit 5     # limit results\nkeg search htop --json      # output JSON\nkeg search bat --fzf        # output TSV for FZF\n```\n\n## 🔄 Update Keg itself\n\nKeg provides a safe self-update mechanism:\n\n* Every 24 hours it checks GitHub for a new version and notifies you.\n* You can manually trigger a check with `keg update --check` (or `-c`).\n* To update to the latest release, run `keg update` (SHA256 verified).\n\n---\n\n## Global options\n\n```bash\nkeg --version               # Show CLI version\nkeg --no-update-check       # Skip update check (for scripting)\n```\n\n---\n\n## 🧪 Testing \u0026 Development\n\n* Runners and HTTP clients are mockable for robust tests.\n* `make build` to build the CLI.\n* `make comp` to generate ZSH completions.\n* Tests use temp dirs and fake clients to avoid side effects.\n* Flag validation (invalid combinations) is covered by dedicated CLI tests.\n\n---\n\n## 🧱 Architecture\n\n**High level:**\n\n* **CLI / Commands**: thin cobra-style commands that delegate to services.\n* **Planner**: computes idempotent actions (install/upgrade/delete) from `keg.yml`.\n* **Runner**: executes actions via a small interface (`Exec(ctx, name, args...)`), easily mockable.\n* **Providers**: distro-specific package providers (brew/apt/dnf/pacman).\n* **Updater**: checks GitHub Releases, verifies SHA256, performs atomic binary replacement.\n* **Config \u0026 State**: XDG paths; human-readable config; no telemetry.\n\n---\n\n## 📝 Roadmap\n\nSee [ROADMAP.md](./ROADMAP.md).\n\n---\n\n## 📄 License\n\nMIT License — see [LICENSE](./LICENSE).\n\n---\n\n## 💡 Tips\n\n* Linux-only by design. macOS might work via Linuxbrew but is not tested. Windows: use WSL. (Mostly because I don't own a Mac and I am not willing to pay an indecent amount of money for a device that I will use only to test Keg. No plans to support Windows natively because Windows is a spyware not an operating system.)\n* Local, human-readable config/state. No cloud, no telemetry, no nonsense.\n* If you break it, you get to keep both pieces. PRs welcome!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrsnakedoc%2Fkeg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrsnakedoc%2Fkeg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrsnakedoc%2Fkeg/lists"}