Sharmory

A single-file library of dev-focused shell functions for Zsh, Bash, and PowerShell — Git shortcuts, Docker/K8s helpers, Go/Node/Python workflow utilities, networking checks, security/encoding helpers, and general productivity tools. No plugin manager, no framework — just source one file.

The GitHub badge counts Release page asset downloads (source zip/tarball). Homebrew tap, Scoop, curl | bash, and irm | iex are not included in that number. npm and PyPI have their own counters.

🚀 Quick Install (1-Line)

macOS / Linux / WSL (Zsh or Bash — auto-detected)

curl -fsSL https://raw.githubusercontent.com/hariharen9/sharmory/main/install.sh | bash

The installer detects your login shell and configures the right file automatically:

• Zsh → installs functions.zsh, patches ~/.zshrc
• Bash → installs functions.bash, patches ~/.bashrc

Both files are always downloaded to ~/.sharmory/ so you can switch shells without re-installing.

Windows (PowerShell 5.1+ & PowerShell Core 7+)

irm https://raw.githubusercontent.com/hariharen9/sharmory/main/install.ps1 | iex

Package managers

Command HUD

Type sharmory with no arguments for an interactive catalog (fzf if installed, otherwise a numbered menu). You can also query it non-interactively:

sharmory                  # interactive HUD
sharmory list             # full catalog
sharmory list git         # one category
sharmory help killport    # description + usage
sharmory run now          # run a catalogued command
sharmory doctor           # environment health check
sharmory setup            # install optional tools (fzf, jq, eza, tldr)
sharmory bench            # source-time benchmark (clean shell)

sharmory-setup is the same as sharmory setup. It only offers small CLI helpers — not Docker, Kubernetes, Go, Node, or Python. You can skip any tool.

🔄 Updating & Maintenance

To update Sharmory to the latest version at any time, run:

sharmory-update

(Works natively in Zsh, Bash, and PowerShell).

📦 Manual Installation (Optional)

git clone https://github.com/hariharen9/sharmory.git ~/.sharmory
echo 'source ~/.sharmory/functions.zsh' >> ~/.zshrc
source ~/.zshrc

curl -o ~/.sharmory/functions.zsh https://raw.githubusercontent.com/hariharen9/sharmory/main/functions.zsh
echo '[[ -f ~/.sharmory/functions.zsh ]] && source ~/.sharmory/functions.zsh' >> ~/.zshrc

git clone https://github.com/hariharen9/sharmory.git ~/.sharmory
echo '[[ -f ~/.sharmory/functions.bash ]] && source ~/.sharmory/functions.bash' >> ~/.bashrc
source ~/.bashrc

curl -o ~/.sharmory/functions.bash https://raw.githubusercontent.com/hariharen9/sharmory/main/functions.bash
echo '[[ -f ~/.sharmory/functions.bash ]] && source ~/.sharmory/functions.bash' >> ~/.bashrc

# Create profile if it doesn't exist yet
if (-not (Test-Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force }

# Clone and source Sharmory
git clone https://github.com/hariharen9/sharmory.git "$HOME\sharmory"
Add-Content $PROFILE '. "$HOME\sharmory\functions.ps1"'
. $PROFILE

Optional dependencies

Most functions work with only core system tools. A few optional tools provide enhanced capabilities:

Every function checks for its dependency and fails gracefully (or falls back to a standard alternative) if it is missing.

Categories

• Navigation & Files — mkcd, up, lsd, fcd, ftext, permsof, extract, compress, duh, sizeof, findbig, emptydirs, dupfind, bak, cwd, clipcopy, clip, treelist, recent, swap, trash, watchrun
• Git — gacp, gclone, gswitch, gstash, grebase, gcamend, gdiffstage, grecentbranch, gpr, gopen, gwip, gunwip, gitundo, gitprune, branchclean, branchage, prdiff, gitlog-today, gitlog-graph, gitcontributors, gitsize, gitconflicts, gitignore, gitbranch-rename, gcleanup
• Docker — dockernuke, dockerclean-images, dclean, dockerlogs, dockersizes, denv, dbuild, dsh
• Kubernetes — kns, ktop, kevents, kdesc, kport, k8sctx, klogs, kexec
• Go — gonew, gowatch, covreport, goclean, goupdate, gomodwhy, gobench
• Node/npm — npmclean, npmscripts, npmoutdated, npmsize
• Python — venvcreate, pyclean, pyfreeze
• Networking — myip, localip, killport, portwho, openports, portscan, dnscheck, certcheck, tlscheck, ipinfo, httpstatus, apihit, headers, flushdns, tcpcheck, pingcheck, weather, shorten, sshconfig, proxy
• Security & Encoding — passgen, genuuid, genssh, pubkey, b64e, b64d, urlencode, urldecode, hashfile, jwtdecode, dotenv-check
• System & Process — mem, cpu, sysinfo, pidtree, fkill, ports, openports, now, timer, diskusage, envdiff
• Productivity — note, todo, hist, mkproject, mktemplate, envload, envswitch, ffind, cheat, calc, qr, jsonpp, diffjson, epoch, retry
• CI/Jenkins — jenk-crumb, jenk-build, jenk-logs, jenk-jobs (needs JENKINS_URL, JENKINS_USER, JENKINS_TOKEN env vars)
• Management — sharmory, sharmory list, sharmory help, sharmory run, sharmory doctor, sharmory setup, sharmory bench, sharmory-update

Function Reference

📁 Navigation & Files

🌿 Git

🐳 Docker

☸️ Kubernetes

🐹 Go

📦 Node / npm

🐍 Python

🌐 Networking & APIs

🔒 Security & Encoding

🖥️ System & Process

✅ Productivity & Misc

🔧 CI / Jenkins

Requires JENKINS_URL, JENKINS_USER, and JENKINS_TOKEN environment variables.

🛠️ Sharmory Management

Testing

All three implementations ship a sandboxed self-test that exercises every function without touching your real system: no real docker/kubectl calls, no real network requests, no real processes killed, no real files outside a throwaway temp directory. External tools that would otherwise hit the network or a live daemon (docker, kubectl, curl/Invoke-RestMethod, dig/Resolve-DnsName, ssh-keygen, fzf, etc.) are mocked for the duration of the run, and the whole sandbox is deleted afterward whether the run passes or fails.

Zsh (macOS/Linux):

chmod +x test-sharmory.zsh
./test-sharmory.zsh                          # tests functions.zsh in the same directory
./test-sharmory.zsh path/to/functions.zsh    # or point at a specific file

Bash (macOS/Linux — requires Bash 4.0+):

chmod +x test-sharmory.bash
./test-sharmory.bash                         # tests functions.bash in the same directory
./test-sharmory.bash path/to/functions.bash  # or point at a specific file

macOS note: The system bash is 3.2. Run the test with a modern Bash: brew install bash && /opt/homebrew/bin/bash test-sharmory.bash

Windows:

.\test-sharmory.ps1
.\test-sharmory.ps1 -FunctionsPath path\to\functions.ps1

Each run prints a PASS/FAIL/SKIP line per function and a summary count.

Exit code is 0 if everything passed or was cleanly skipped, 1 if anything actually failed — safe to wire into CI.

Platform Verification: All three implementations (Zsh, Bash, PowerShell) are verified end-to-end against live interpreters with fully sandboxed test suites. In Zsh, early testing caught variable collisions with the special $path array. In Bash, the test runner was adapted to work with Bash 3.2 (macOS default) as well as Bash 4.0+ (required for the functions themselves). In PowerShell, testing verified parser compatibility across Windows PowerShell 5.1 and modern PowerShell Core (7+).

⚠️ Plugin Manager Compatibility

If you use oh-my-zsh or another plugin manager, some function names may already exist as aliases. Sharmory automatically clears any conflicts at load time — sourcing it will always be clean.

🗑️ Uninstalling

macOS / Linux / WSL (Zsh or Bash)

curl -fsSL https://raw.githubusercontent.com/hariharen9/sharmory/main/uninstall.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/hariharen9/sharmory/main/uninstall.ps1 | iex

Contributing

PRs adding new functions welcome. Keep the style consistent:

• one function, one job
• Usage: line printed when required args are missing
• guard against missing optional dependencies rather than hard-failing
• a one- or two-line comment above the function explaining what it does
• new functions must be added to all three files (functions.zsh, functions.bash, functions.ps1) and the registry in each, with a matching test case in each test file

License

MIT