Quickstart

From zero to a fully managed workstation in a few minutes.

Install hams

Pick whichever fits your habits:

curl (recommended)


bash -c "$(curl -fsSL https://github.com/zthxxx/hams/raw/main/scripts/install.sh)"

The script figures out your platform (darwin/arm64, linux/amd64, linux/arm64), drops the latest binary in /usr/local/bin/hams, and leaves a channel marker so hams self-upgrade knows how you got here.

Homebrew


brew install zthxxx/tap/hams

Via the official Homebrew tap. Later, hams self-upgrade defers to brew upgrade hams, so it fits into your regular brew habits.

GitHub Releases

Grab the binary for your platform from GitHub Releases :

Platform	Architecture	File
macOS	Apple Silicon (M-series)	`hams-darwin-arm64`
Linux	x86-64	`hams-linux-amd64`
Linux	ARM64	`hams-linux-arm64`


# Example, macOS Apple Silicon
curl -Lo hams https://github.com/zthxxx/hams/releases/latest/download/hams-darwin-arm64
chmod +x hams
sudo mv hams /usr/local/bin/hams

Confirm you’re good:


hams --version
# hams v0.1.0 (commit: abc1234, built: 2026-04-12)

Agent skill (optional, for Claude Code / Codex)

If you use an agent like Claude Code or Codex alongside hams, install the shipped skill so the agent reaches for hams <provider> instead of the raw package manager when your goal is durable environment state:


npx skills add https://github.com/zthxxx/hams --skill system-packages-maintenance-hams

The skill is a short reference — it enumerates the 14 builtin providers, spells out when hams is worth reaching for vs when the bare tool is fine, and points the agent to hams <command> --help for flag-level detail. No runtime cost; it just improves the agent’s defaults.

Install something (and let hams remember)

Usage is plain: take whatever command you’d normally type, stick hams in front of it.


# Install htop (a nicer top) via Homebrew, and write it to the Hamsfile
hams brew install htop
 
# Globally install serve through pnpm, also recorded
hams pnpm add serve
 
# Set git identity, also recorded
hams git config --global user.name "Your Name"
hams git config --global user.email "[email protected]"

Behind each command, hams quietly does two things:

Runs the actual tool (brew install htop, pnpm add -g serve)
Writes the installation into the matching Hamsfile (macOS/Homebrew.hams.yaml, macOS/pnpm.hams.yaml)

On the very first hams <provider> … invocation, hams scaffolds a store directory for you — creates ~/.local/share/hams/store/, runs git init, writes a template .gitignore + hams.config.yaml, and seeds your global config with profile_tag: default and machine_id: <hostname>. You don’t need to run hams store init first; the first install command takes care of it.

Restore everything on a fresh machine

This is where hams earns its keep. On a brand-new machine:

First, install hams itself


bash -c "$(curl -fsSL https://github.com/zthxxx/hams/raw/main/scripts/install.sh)"

hams bundles go-git, so you don’t need to install git first. Classic chicken-and-egg dodged.

Apply from your store repo


# One-shot: clone, pick the profile, apply. --tag maps to the directory
# inside your store (macOS/, openwrt/, work-linux/, …). --bootstrap lets
# hams auto-install provider prerequisites under your consent.
hams apply --bootstrap --from-repo=<your-username>/hams-store --tag=macOS

Replace the placeholders with your GitHub username, store repo, and the profile tag you use for this kind of machine. Behind the scenes hams clones the repo, writes ~/.config/hams/hams.config.yaml with profile_tag: macOS + machine_id: <hostname>, and starts the apply run.

Forgot --tag? On an interactive terminal hams drops into a two-question prompt for profile tag

machine ID. In CI / scripts, always pass --tag=<tag> so the run is fully non-interactive.

Bootstrap consent. On an interactive terminal, --bootstrap is optional — hams shows a [y/N/s] prompt before running any install script. In CI / scripts, pass --bootstrap explicitly (or --no-bootstrap to fail fast). See the apply page for the full list of bootstrap-supported providers.

Enter your sudo password, if anything needs it

If your profile uses a privileged provider (like apt on Linux), hams asks for sudo once at the start:


Some providers require sudo. Enter your password to continue:
Password:

Once is all it needs. hams keeps the sudo ticket warm in the background (refreshing every 4 minutes) so apply can run to completion without popping another prompt.

Watch it work


hams apply  •  profile: macOS  •  machine: MacbookProM3
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[Homebrew]  Refreshing state...                      ✓
[Homebrew]  git                  already installed   ✓
[Homebrew]  ripgrep              installing...        ✓
[Homebrew]  htop                 installing...        ✓
[Homebrew]  fd                   installing...        ✓
[pnpm]      Refreshing state...                      ✓
[pnpm]      serve                installing...        ✓
[git-config] user.name           setting...           ✓
[git-config] user.email          setting...           ✓

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
8 resources  •  7 installed  •  1 already present  •  0 failed
Log: ~/.local/share/hams/2026-04/20260412T143022.log

Double-check


# What's managed, and is it all happy?
hams list
 
# Or zoom in on one provider
hams brew list

Push your changes back

Once you’ve installed new things on this machine, push the Hamsfiles back to the store so the other machines can catch up:


# From inside your store directory
hams store push
# Stages Hamsfile changes, commits, pushes to the remote

Prefer to drive git yourself? Go for it. Hamsfiles are plain YAML, nothing hams does stops you from git add && git commit && git push.

Where to go next

CLI Reference — every command and flag
Providers — what each of the 14 builtin providers does
Schema Reference — the shape of Hamsfiles and config YAML

Not sure about an upcoming apply? Try hams --dry-run apply first — it prints exactly what it would do, without touching a thing.