README
¶
eng CLI
__ __
| \ \
______ _______ ______ _______| ▓▓\▓▓
/ \| \ / \ / \ ▓▓ \
| ▓▓▓▓▓▓\ ▓▓▓▓▓▓▓\ ▓▓▓▓▓▓\ | ▓▓▓▓▓▓▓ ▓▓ ▓▓
| ▓▓ ▓▓ ▓▓ | ▓▓ ▓▓ | ▓▓ | ▓▓ | ▓▓ ▓▓
| ▓▓▓▓▓▓▓▓ ▓▓ | ▓▓ ▓▓__| ▓▓ | ▓▓_____| ▓▓ ▓▓
\▓▓ \ ▓▓ | ▓▓\▓▓ ▓▓ \▓▓ \ ▓▓ ▓▓
\▓▓▓▓▓▓▓\▓▓ \▓▓_\▓▓▓▓▓▓▓ \▓▓▓▓▓▓▓\▓▓\▓▓
| \__| ▓▓
\▓▓ ▓▓
\▓▓▓▓▓▓
A modern, modular CLI tool for developer automation, dotfiles management, system utilities, and project codemods. Built in Go, designed for extensibility and productivity.
Features
- Git Repository Management — Bulk operations across multiple git repositories with intelligent branch detection
- Docker Compose Swarms — Lifecycle management (
up,down,pull,status,logs) for multi-service compose stacks - Project Management — Organize and manage groups of related repositories as logical projects
- Dotfiles Management — Manage dotfiles via a bare git repo, with sync/fetch/checkout helpers
- Dotfiles Secrets — Backup and restore manifest-managed env files with Bitwarden Secrets Manager
- System Utilities — macOS/Linux helpers (kill port, kill process, proxy, update, compaudit fix)
- File Utilities — Find and delete files by extension, filename, or glob pattern
- Codemod Automation — Project codemods (lint setup, prettier, copilot instructions)
- Tailscale Helpers — Bring Tailscale service up/down
- GitLab Integration — Manage MR rules and authentication via glab CLI
- Config Management — Centralized config via Viper with automatic migration
- Auto-Update — Version checking and Homebrew auto-update support
Installation
One-line script (curl)
Works on macOS and Linux without Go or Homebrew. Downloads the matching
release asset from GitHub Releases, verifies its SHA256 checksum, and installs
to /usr/local/bin (uses sudo only when needed):
curl -sSfL https://raw.githubusercontent.com/eng618/eng/main/install.sh | sh
Pin a version or install user-local (no sudo, ensure the dir is on PATH):
curl -sSfL https://raw.githubusercontent.com/eng618/eng/main/install.sh | sh -s -- -v v0.17.5
curl -sSfL https://raw.githubusercontent.com/eng618/eng/main/install.sh | INSTALL_DIR=$HOME/.local/bin sh
ENG_VERSION=v0.17.5 INSTALL_DIR=$HOME/.local/bin sh install.sh
Update anytime with:
eng version -u
On Windows, run the same command from Git Bash (requires unzip).
Homebrew
brew tap eng618/eng
brew install eng
Or directly:
brew install eng618/eng/eng
Go Install
go install github.com/eng618/eng@latest
From Source
git clone https://github.com/eng618/eng.git
cd eng
task install # or: go install .
Usage
eng [command] [flags]
Quick Start
# Configure your development folder
eng config git-dev-path ~/Development
# Sync all git repositories
eng git sync-all
# Install dotfiles from your repo
eng dotfiles install
# Backup or restore manifest-managed dotfiles secrets
eng dotfiles secrets backup
eng dotfiles secrets restore
# Optional: run SSH setup directly if you want to prepare keys first
eng ssh setup
# Setup a new development machine
eng setup
# Check version and updates
eng version
Private Dotfiles Quickstart
For private GitHub dotfiles repositories, eng dotfiles install now validates dotfiles config first,
checks core prerequisites, and only then runs GitHub SSH setup when the configured repo URL uses SSH.
If cloning fails due to SSH auth, run:
eng ssh setup
Dotfiles Secrets
eng dotfiles secrets turns the manifest-driven bws backup and restore flow into a first-class CLI feature.
By default it looks for the manifest at $HOME/bin/secrets/server.manifest using the configured dotfiles
worktree, and restores files relative to that worktree. The Bitwarden Secrets Manager project UUID can come
from --project-id, BWS_PROJECT_ID, or the manifest comment header.
# Backup managed env values into Bitwarden Secrets Manager
eng dotfiles secrets backup
# Restore env files from their tracked .example templates
eng dotfiles secrets restore
# Validate manifest/template/secret consistency
eng dotfiles secrets doctor
eng setup dotfiles now runs eng dotfiles secrets restore automatically after install when:
- the manifest exists at the configured dotfiles worktree (
bin/secrets/server.manifest) BWS_ACCESS_TOKENis set
If those prerequisites are not met, the restore step is skipped safely.
Available Commands
| Command | Description |
|---|---|
eng git |
Manage multiple git repositories (sync, fetch, pull, push, status) |
eng compose |
Manage Docker Compose swarms (up, down, pull, status, logs) — alias: swarm |
eng project |
Manage project-based repository collections |
eng dashboard |
Interactive TUI command center for monitoring and managing projects |
eng dotfiles |
Manage dotfiles (install, sync, fetch, checkout, status) |
eng setup |
Setup workstation (asdf, dotfiles, oh-my-zsh, gpg) |
eng gpg |
Manage GPG keys (setup, renew, sync) |
eng ssh |
Manage SSH keys for GitHub (setup) |
eng proxy |
Manage proxy profiles |
eng update |
Update system packages, brew, asdf, and IDE |
eng clean |
Clean host storage (docker, journals, caches) |
eng kill |
Kill processes by port or PID |
eng files |
File utilities (find-and-delete, find-non-movie-folders) |
eng codemod |
Project codemods (lint-setup, prettier, copilot) |
eng tailscale |
Tailscale helpers (up, down) — alias: ts |
eng gitlab |
GitLab integration (mr-rules, auth) |
eng version |
Show version, check for updates |
eng config |
Manage CLI configuration |
eng logs |
View session logs from verbose commands (list, show, clean) |
eng doctor |
Check system health and verify dependencies — alias: doc |
For detailed command documentation, see docs/reference/commands.md.
Global Flags
--config string # Config file (default: $HOME/.eng.yaml)
-v, --verbose # Verbose output
-h, --help # Help for any command
Documentation
Full index: docs/README.md (Diátaxis: tutorials, how-tos, reference, explanation).
- Getting started — Install, first run, first project (~10 minutes)
- Command Reference — Complete documentation for all commands
- Architecture — Technical architecture and design
- Roadmap — Completed UI/UX roadmap
- Releasing — Automated release and Homebrew publication process
- Changelog — Version history and release notes
Support
- Issues: GitHub Issues
Contributing
Contributions are welcome! Please follow these guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Enable the pre-push hook (one-time per clone):
git config core.hooksPath .githooks(blocks pushes with stale generated docs; bypass withgit push --no-verify) - Make your changes following the Go style guidelines
- Run validation:
task validate(runs format, lint, and tests) - Commit your changes using Conventional Commits
- Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Development Commands
task build # Build the binary
task install # Install to $GOPATH/bin
task docs # Generate Markdown documentation for CLI commands
task lint # Run golangci-lint
task test # Run tests with coverage
task validate # Run format + lint + test
task changelog # Generate changelog
task release # Create a release (goreleaser)
See Taskfile.yaml for all available tasks.
Authors
- Eric N. Garcia — @eng618
License
MIT License © 2023–2026 Eric N. Garcia
Links
Documentation
¶
Overview ¶
Copyright © 2023 Eric N. Garcia <eng618@garciaericn.com>
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
codemod
Package codemod provides helpers for codemods and project automation.
|
Package codemod provides helpers for codemods and project automation. |
|
config
Package config provides subcommands for managing the eng CLI configuration.
|
Package config provides subcommands for managing the eng CLI configuration. |
|
doctor
Package doctor provides the 'eng doctor' diagnostic command to check workstation dependencies, tools, configuration paths, and runtime health.
|
Package doctor provides the 'eng doctor' diagnostic command to check workstation dependencies, tools, configuration paths, and runtime health. |
|
dotfiles
Package dotfiles provides cobra commands for managing user dotfiles via a bare git repository.
|
Package dotfiles provides cobra commands for managing user dotfiles via a bare git repository. |
|
git
Package git provides cobra commands for managing multiple git repositories in a development folder.
|
Package git provides cobra commands for managing multiple git repositories in a development folder. |
|
project
Package project provides cobra commands for managing project-based repository collections.
|
Package project provides cobra commands for managing project-based repository collections. |
|
version
Package version implements the 'eng version' command, which displays the application's version information and checks for available updates.
|
Package version implements the 'eng version' command, which displays the application's version information and checks for available updates. |
|
internal
|
|
|
config
Package config is a helper package to facilitate getting and setting config values using Viper.
|
Package config is a helper package to facilitate getting and setting config values using Viper. |
|
execx
Package execx centralizes process execution behind mockable entry points.
|
Package execx centralizes process execution behind mockable entry points. |
|
log
Package log is a wrapper around colorizing the log output.
|
Package log is a wrapper around colorizing the log output. |
|
paths
Package paths centralizes home-directory resolution and path expansion.
|
Package paths centralizes home-directory resolution and path expansion. |
|
project
Package project provides the core domain logic for managing multi-repository workspaces.
|
Package project provides the core domain logic for managing multi-repository workspaces. |
|
runlog
Package runlog manages per-command session log files.
|
Package runlog manages per-command session log files. |
|
ui
Package ui provides reusable interactive terminal UI components, standardized theming, and wrappers around the "charmbracelet/huh" and "charmbracelet/bubbles" libraries.
|
Package ui provides reusable interactive terminal UI components, standardized theming, and wrappers around the "charmbracelet/huh" and "charmbracelet/bubbles" libraries. |
|
version
Package version holds the application's build-time version metadata.
|
Package version holds the application's build-time version metadata. |
|
tools
|
|
|
gendocs
command
|